Access Token Request

General

Request for access token is a functionality given by our new API to facilitate integration of an ATS (Application Tracking System) without internal systems, which demand a token for each of our clients. Previously, this was a manual request, in which companies asked directly Catho for the token, now this request can be done via API. You can check all our documentation using Swagger.


APIs Modeling

All services available by the API use the REST (Representational State Transfer) technology, an architecture for the disponibilization of resources through distributed systems, Popularly used over HTTP. Below we can see examples of how those services are formed:

APIs modeling illustration

Being that:

  • • Hostname: service's main address.
  • • API's version: version of the service being consumed.
  • • Root Resource: service's name.

As from the root resource, we can make our POST, for request of access token, as the below example:

curl -X POST 'http://api.catho.com.br/ats/v1/access-token/' \
-H 'Content-Type: application/json' \
-H 'Content-Type: text/plain' \
-H 'client: client id - generated by the dev.catho portal' \
-H 'secret: secret - generated by the dev.catho portal'' \
-d '{
	"email":"xxxxxx@email.com",
	"cnpj":"00.000.000/0000-00",
	"callback":"http://callback",
	"ats_name":"nome ats"
}'

Success example:

code: 201

After accomplishing the token request, the recruiter will be requested through their email the request from ATS (Integrator) to publish job vacancies in their name. The recruiter needs to "Allow" for proceeding the token generation process.


Access token email illustration

ATTENTION: only after the request be "AUTHORIZED", the ATS (Integrator) will be allowed to register job vacancies in the recruiter's name.


Validations errors

These errors prevent the processing of the sent action. To resend these request it will be necessary to alter the body and head data's or url's parameters according to the returned errors instructions.

Look at an example where the fields were not informed on the POST body:

{
    "message": "Parâmetros email, cnpj, callback, ats_name inválidos",
    "code": "RAT0001"
}

Check below a list of all errors that can be returned:

Code Message
RAT0001 Parameters email, cnpj, callback, ats_name are invalid.
RAT0002 Parameters email, cnpj e callback are required.
RAT0003 Unregistered user.
RAT0004 Unregistered company.
RAT0005 Fail to register ATS.
RAT0006 Recruiter isn't linked to the provided CNPJ.
RAT0007 Company doesn't have the status as ACTIVE or INSPECTION.
RAT0008 Header client is mandatory.
RAT0010 Client not found.
RAT0011 Error when linking the ATS to the company.
REC000 Error when validate JSON. Is the structure correct?
REC001 CNPJ field is mandatory.
REC002 User name is mandatory.
REC003 Email is mandatory.
REC004 CPF is mandatory.
REC005 Role is mandatory.
REC006 Phone is mandatory.
REC008 Value from the gender field must be 'FEMALE' or 'MALE'.
ATG0001 Access token creation failed!
ATG0002 Access token creation failed!
ATG0003 Access token creation failed!
PB0001 Fail during the access token sent proccess!
RAM001 Field 'permission_granted' only accepts one of the following values: 0 or 1.
RAM002 The approval request expired or the order identifier isn't valid.
EA0001 Invalid parameter.
EA0002 Fail to find the recruiter.
EA0003 Fail to find ATS.
EA0004 ATS not found.
EA0005 Error generating email link.
EA0006 Error sending email.
EA0007 Fail to find company.
AT0000 Error trying to process datas.

Token request flow

Just below is possible to understand how is accomplished the token request at Catho.

Token request flow illustration