Nossa API utiliza respostas HTTP convencionais para indicar sucesso ou falha nas requisições. Respostas com status 2xx indicam sucesso, status 4xx indicam falhas decorrentes de erros nas informações enviadas, e status 5xx indicam erros internos em nosso servidor.
| Código HTTP | Descrição |
|---|---|
| 200 OK | A resposta é um sucesso e contém uma lista de registros ou um registro isolado. |
| 201 Created | A resposta é um sucesso e o registro foi gravado. |
| 202 Accepted | A resposta é um sucesso, os dados foram aceitos e serão processados em breve. |
| 204 No Content | A resposta é um sucesso, porém não há nada para ser exibido. |
| 400 Bad Request | A resposta é um erro com relacionado a um conjunto de informações mal formadas, sem ligação com o valor enviado nos campos da requisição. |
| 401 Unauthorized | A resposta é um erro relacionado aos dados da autenticação. |
| 404 Not Found | A resposta é um erro e Indica que o registro ou endpoint não existe ou não foi encontrado. |
| 422 Unprocessable Content | A resposta é um erro relacionado a dados enviados nos campos. |
| 423 Locked | A resposta é um erro e indica que um recurso que você perdeu acesso a um recurso específico ou sua conta foi bloqueada. |
| 429 Too Many Requests | A resposta é um erro relacionado a quantidade de requisições feitas ou limites de uso. |
Nossa api foi projetada para funcionar de forma intuitiva, clara e objetiva. Por isso nossas respostas http são ligadas ao método HTTP utilizado e o tipo de ação desejada. Segue abaixo os padrões:
| Código HTTP | Metodo HTTP | Ação atrelada |
|---|---|---|
| 200 | GET | Exibição de qualquer lista de registros, contendo no mínimo 1 registro. |
| 200 | GET | Exibição de qualquer registro usando o identificador único, se o registro existir. |
| 201 | POST | Cadastrar qualquer tipo de registro novo, por exemplo: um cliente ou uma cobrança. |
| 202 | QUALQUER | Ao enviar qualquer dado que não seja possivel mostrar o resultado na mesma requisicao. |
| 204 | GET | Exibição de qualquer lista de registro, quando não ouver nenhum registro. |
| 204 | PUT, PATH | Atualização de qualquer registro ou dado, caso haja sucesso. |
| 204 | DELETE | Exclusão de qualquer registro ou conjunto, caso não tenha sido excluido antes e haja sucesso. |
| 400 | POST, PUT, PATCH, DELETE | Durante a Inserção, atualização ou exclusão de um registro ou conjunto de registros com algum impeditivo, que não seja permissão específica nem dados de autenticação. |
| 401 | QUALQUER | Executar qualquer ação usando dados de autenticação incorreta. |
| 404 | GET, PUT, PATCH, DELETE | Exibir registro, atualizar, ou deletar um registro específico usando identificador único, que não tenha sido previamente cadastrado ou que já tenha sido removido, ou acessar um endpoint que não existe. |
| 422 | GET|DELETE | Exibição ou exclusão de específico que nescessite do identificador único inválido, ou uso de filtros de registros |
| 422 | POST,PUT,PATCH | Cadastrar ou atualização de qualquer registro contendo informações incorretas nos campos enviados. |
| 423 | QUALQUER | Durante qualquer requisição, no caso de bloqueios de recurso específico ou conta total. |
| 429 | QUALQUER | Durante qualquer requisição, ao atingir limites da api. |
Todos os endpoints da API recebem e respondem em JSON.
Exemplo de resposta para HTTP 200, contendo lista de registros:
Caso de uso: Carregar a lista de todos os clientes.
{
"message": "Exibindo registros de clientes.",
"data": [
{
"cell_phone": "5583981234567",
"city": "São Paulo",
"company_name": "Exemplo LTDA",
"complement": "Apto 101",
"cpfCnpj": "12345678901",
"created_at": "2024-04-12T20:34:43.560000Z",
"deleted_at": null,
"email": "[email protected]",
"full_name": "John Doe",
"identifier": "0e01234567890b01ed0123456fghi1cf0",
"neigh": "Centro",
"street": "Rua Exemplo",
"street_number": "123",
"totalValuePending": 0,
"uf": "SP",
"updated_at": "2024-04-12T20:34:43.560000Z",
"zip_code": "12345678"
},
{
"cell_phone": "5583981234588",
"city": "São Paulo",
"cpfCnpj": "12345678000190",
"company_name": "Exemplo 2 LTDA",
"complement": "Apto 102",
"created_at": "2024-04-12T20:34:43.560000Z",
"deleted_at": null,
"email": "[email protected]",
"full_name": "John Doe",
"identifier": "0e01234567890b01ed0123456fghi1cf0",
"neigh": "Centro",
"street": "Rua Exemplo",
"street_number": "123",
"totalValuePending": 0,
"uf": "SP",
"updated_at": "2024-04-12T20:34:43.560000Z",
"zip_code": "12345678"
}
]
}
Exemplo de resposta para HTTP 200, contendo 1 registro específico:
Caso de uso: Carregar registro do cliente de John doe, usando o Identificador único
{
"message": "Exibindo registro",
"data": {
"cell_phone": "5583981234567",
"city": "São Paulo",
"cpfCnpj": "12345678901",
"company_name": "Exemplo LTDA",
"complement": "Apto 101",
"created_at": "2024-04-12T18:49:03.027000Z",
"deleted_at": null,
"email": "[email protected]",
"full_name": "John Doe",
"identifier": "0e01234567890b01ed0123456fghi1cf0",
"neigh": "Centro",
"street": "Rua Exemplo",
"street_number": "123",
"totalValuePending": 21.1,
"uf": "SP",
"updated_at": "2024-04-16T00:20:54.340000Z",
"zip_code": "12345678"
}
}
Exemplo de resposta para HTTP 201:
Caso de uso: Cadastrar o cliente John Doe.
{
"message": "Cliente cadastrado com sucesso.",
"data": {
"cell_phone": "5583981234567",
"city": "São Paulo",
"cpfCnpj": "12345678901",
"company_name": "Exemplo LTDA",
"complement": "Apto 101",
"created_at": "2024-04-12T18:49:03.027000Z",
"email": "[email protected]",
"full_name": "John Doe",
"identifier": "0e01234567890b01ed0123456fghi1cf0",
"neigh": "Centro",
"street": "Rua Exemplo",
"street_number": "123",
"uf": "SP",
"zip_code": "12345678"
}
}
Exemplo de resposta para HTTP 202:
Caso de uso: Ao solicitar extono, em que o procesamento é feito após uma verificação de dados tais como valor pago, prazo de validade e a conta de destino, e não é possivel informar o resultado na mesma requisição.
{
"message": "Solicitação efetuada com sucesso.",
}
Exemplo de resposta para HTTP 204:
Casos que podem ocorrer: Carregar lista de clientes antes de ter cadastrado no mínimo 1, Filtrar clientes pelo cpf que não está cadastrado, Excluiu ou atualizou com sucesso os dados de um registro existente usando o Identificador único.
{}
Exemplo de resposta para HTTP 400:
Casos que podem ocorrer: Remover um cliente que tem dividas ativas. Por padrão você pode remover tanto o cliente quanto uma dívida, porém ter uma divida ativa é um impeditivo para a exclusão de um cliente.
{
"message": "Não é possível excluir o registro do cliente.",
"errors": {
"installments": "Cliente com dívidas"
}
}
Exemplo de resposta para HTTP 401:
Casos que podem ocorrer: Não incluir o header X-Customer-Private-Key na requisição ou incluir o header X-Customer-Private-Key com um valor inválido, não cadastrado ou alterado.
{
"error": {
"auth": "Dados incorretos. Para mais informações entrar em contato com a Raims Pay"
}
}
Exemplo de resposta para HTTP 404:
Casos que podem ocorrer: Exibir, ou atualizar um registro, ou excluir um registro que nunca existiu ou o identificador único do registro está incorreto.
{
"message": "Registro não encontrado",
"errors": {
"identifier": "O identificador único digitado não existe, não foi cadastrado ou foi removido."
}
}
Exemplo de resposta para HTTP 422:
Casos que podem ocorrer: Cadastrar um cliente sem colocar o nome, ou com CPF/CNPJ inválido.
{
"message": "O Nome completo é obrigatório.",
"errors": {
"cpfCnpj": [
"O CPF ou CNPJ informado é inválido."
],
"full_name": [
"O Nome completo é obrigatório."
]
}
}
Exemplo de resposta para HTTP 423:
Casos que podem ocorrer: Tentativa de saque, após solicitação de extorno por cliente ou bloqueio total da cont
{
"error": {
"suspended_account": "Cadastro bloqueado. Para mais informações entrar em contato com a Raims Pay."
}
}
Exemplo de resposta para HTTP 429:
Casos que podem ocorrer: Você atinge o limite padrão de requisições para 12 horas corridas, ou o limite de requisições simultaneas.
{
"message": "Limite de requisições excedido",
"errors": {
"rate_limit": "O seu limite de 25000 requisições em 12 horas foi excedido. Entre em contato com a Raims Pay para aumentar seu limite.",
"rate_request_recurring": "O seu limite de 50 requisições em simultaneas foi excedido. Entre em contato com a Raims Pay para aumentar seu limite."
}
}