About our APIs

This manual has been created to help you explore our documentation and better understand all the features available.

At Voluti, we describe APIs using a widely used standard for describing APIs, the OpenAPI Specification. OpenAPI includes information about the data structure, response models, object definitions, API fields, data types, relationships between objects and much more.

Structure of an endpoint

The following is a detailed description of an endpoint structure

1. endpoint title.
2. To better understand how an endpoint works, they all have a description.
3. Security details on how to authorize with the API.
4. Endpoint request body (Request body and query parameters).
5. Response examples.
6. Simulation functionality.
7. Programming languages example types.

Errors

When integrating with APIs, it is common to receive error responses that indicate problems with the request or the server. These errors are essential for identifying what went wrong and how to adjust the request or the system to ensure effective communication with the API.

The API returns errors in JSON format with the following structure. See the examples below:

400

{
  "type": "https://pix.bcb.gov.br/api/v2/error/CobOperacaoInvalida",
  "title": "Cobrança inválida.",
  "status": 400,
  "detail": "A requisição que busca alterar ou criar uma cobrança para pagamento imediato não respeita o _schema_ ou está semanticamente errada.",
  "violacoes": [
    {
      "razao": "O campo cob.valor.original não respeita o _schema_.",
      "propriedade": "cob.valor.original"
    }
  ]
}

401

{
    "message": "Unauthorized"
}

403

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/CobPayloadNaoEncontrado",
  "title": "Cobrança não encontrada.",
  "status": 404,
  "detail": "A cobrança em questão não foi encontrada para a localização requisitada."
}

503

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

HTTP status code

The table below presents a list of errors that may be returned, accompanied by a brief description of the possible causes.

HTTP status code	Text	Description
400	Bad Request	The request was invalid, which can occur for various reasons - such as malformed JSON or a violation of rules (e.g. attempting to redeem an expired voucher).
401	Unauthorized	Authentication has failed or has not yet been provided.
403	Forbidden	This occurs when the server understands the request made by the client, but refuses to authorize it - access denied.
404	Not Found	The requested resource was not found.
405	Method Not Allowed	The request used a method (GET, POST, etc.) that is not available for a given resource. The error details include a hint as to which methods are allowed.
500	Internal Server Error	An internal API error has occurred. Don't worry, we track and check all these errors and try to react as quickly as possible.
503	Service Unavailable	Server is not available to process the request at the moment.

❗Warning:

In addition to the errors listed above, others may occur. That's why it's important not to rely solely on error codes, but also to check the full content of the JSON.