Copy page

Guias

Autenticação

Toda requisição à API da Quyta exige um token de API enviado no header Authorization, no formato Bearer:

Code
curl https://app.quyta.com.br/api/v1/debts \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

Não há login, refresh token nem fluxo OAuth: o token é gerado no painel da Quyta e usado diretamente.

Headers de conteúdo

A API sempre responde JSON, inclusive nos erros. Você não precisa negociar formato: não há Accept obrigatório, e um GET só precisa do Authorization.

Code
curl "https://app.quyta.com.br/api/v1/debts" \
  -H "Authorization: Bearer $QUYTA_TOKEN"

O único header de conteúdo que importa é o Content-Type: application/json em POST e PUT — e por um motivo funcional, não de formato de resposta: sem ele o servidor não interpreta o corpo como JSON, lê os campos como vazios e devolve 422 em tudo.

Requisição	Header necessário
GET, DELETE	nenhum além do Authorization
POST, PUT	Content-Type: application/json

Como obter um token

Os tokens são criados no painel da Quyta, na área de configurações de API. Ao criar um token você define:

1. A conta a que ele pertence — o token só enxerga os dados dessa unidade.
2. As permissões que ele carrega (veja a tabela abaixo).
3. A validade, se o token deve expirar.

Onde guardar

O token dá acesso de escrita à sua carteira. Trate-o como senha:

• guarde em variável de ambiente ou cofre de segredos, nunca no código-fonte;
• nunca o exponha em front-end, aplicativo móvel ou log;
• use tokens distintos por ambiente e por sistema integrado — assim revogar um não derruba os outros;
• revogue imediatamente qualquer token que possa ter vazado.

Permissões

Cada endpoint exige uma permissão específica. Um token só consegue chamar aquilo que lhe foi concedido — conceda o mínimo necessário.

Permissão	Libera
customers.list	GET /customers
customers.show	GET /customers/{id}
customers.create	POST /customers e PUT /customers/{id}
customers.update	Telefones e e-mails: POST e DELETE em /customers/.../phones e /emails
debts.list	GET /debts
debts.show	GET /debts/{id}
debts.create	POST /debts
debts.update	PUT /debts/{id}
debtgroups.list	GET /debtgroups
debtgroups.show	GET /debtgroups/{id}

Um exemplo prático: uma rotina noturna que só envia carteira precisa de customers.create, debts.create e debtgroups.list. Um painel interno que apenas consulta situação precisa somente das permissões *.list e *.show.

Erros de autenticação

Todos seguem o mesmo formato de resposta:

Code
{
  "message": "Token não encontrado",
  "error_code": "API_AUT_02",
  "status_code": 401
}

error_code	HTTP	O que aconteceu	O que fazer
API_AUT_01	401	Header Authorization ausente ou malformado.	Envie Authorization: Bearer {token}.
API_AUT_02	401	Token não existe.	Confira se copiou o token inteiro e se está no ambiente certo.
API_AUT_03	401	Token expirado.	Gere um novo token no painel.
API_AUT_04	401	Token revogado.	Gere um novo token. Se você não o revogou, avise o time de segurança.
API_AUT_05	403	Token válido, mas sem a permissão exigida.	Conceda a permissão no painel ou use um token adequado.

A diferença entre 401 e 403 importa no seu tratamento de erros: 401 significa "esse token não serve" — repetir a requisição não adianta. 403 significa "esse token é válido, mas não pode fazer isso" — é um problema de configuração, não de credencial.

Limite de requisições

A API aceita 1.000 requisições por minuto por token. Ao ultrapassar esse limite as requisições passam a responder 429 Too Many Requests.

Para cargas grandes, veja as recomendações em Sincronizando a carteira.