Copy page

Guias

Primeiros passos

Este guia leva você do token em mãos até a primeira dívida entrando em cobrança. São quatro passos e todos usam curl — traduza para a sua linguagem à vontade.

Antes de começar, tenha um token de API com as permissões debtgroups.list, customers.create e debts.create.

Code
export QUYTA_TOKEN="seu_token_aqui"
export QUYTA_API="https://app.quyta.com.br/api/v1"

1. Descubra o grupo de dívidas

O grupo define a régua de cobrança que será aplicada. Ele é configurado no painel da Quyta; pela API você só o consulta para pegar o id.

Code
curl -s "$QUYTA_API/debtgroups" \
  -H "Authorization: Bearer $QUYTA_TOKEN"

Code
{
  "data": [
    { "id": 1, "business_unit_id": 1, "name": "Carteira principal — 30 a 90 dias" },
    { "id": 2, "business_unit_id": 1, "name": "Carteira principal — acima de 90 dias" }
  ],
  "meta": { "total": 2, "per_page": 15, "current_page": 1, "total_pages": 1 }
}

Essa lista muda raramente. Consulte uma vez e guarde o mapeamento no seu sistema, em vez de chamá-la a cada dívida.

2. Crie o cliente

Todos os campos abaixo são obrigatórios, incluindo o endereço completo e ao menos um e-mail e um telefone.

Code
curl -s -X POST "$QUYTA_API/customers" \
  -H "Authorization: Bearer $QUYTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fulano de Tal",
    "document": "12345678909",
    "addr_zipcode": "01001000",
    "addr_street": "Rua Exemplo",
    "addr_number": "100",
    "addr_district": "Centro",
    "addr_city": "São Paulo",
    "addr_state": "SP",
    "addr_extra": "Sala 2",
    "emails": ["fulano@example.com"],
    "phones": ["+5511999999999"]
  }'

A resposta traz o cliente criado, com o id que você vai usar no próximo passo:

Code
{
  "id": 42,
  "business_unit_id": 1,
  "name": "Fulano de Tal",
  "document": "12345678909",
  "person_type": "F",
  "emails": [{ "id": 1, "email": "fulano@example.com" }],
  "phones": [{ "id": 1, "phone": "+5511999999999" }],
  "created_at": "2026-08-27T10:30:00Z",
  "updated_at": "2026-08-27T10:30:00Z"
}

O person_type é deduzido do document: CPF vira F, CNPJ vira J.

Repare que o telefone volta em E.164 (+5511999999999). A Quyta normaliza para esse formato antes de validar, então (11) 99999-9999 e 11999999999 chegam ao mesmo resultado — mas enviar já com + e DDI é o único jeito sem ambiguidade. Os detalhes estão em Conceitos.

3. Crie a dívida

Agora amarre o cliente ao grupo de dívidas:

Code
curl -s -X POST "$QUYTA_API/debts" \
  -H "Authorization: Bearer $QUYTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 42,
    "debt_group_id": 1,
    "original_value": 1000.00,
    "due_date": "2026-05-15",
    "description": "Parcela 05/2026 — contrato 88213",
    "external_id": "TIT-88213",
    "origin_contract_id": "767",
    "origin_date": "2026-04-15"
  }'

Code
{
  "id": 3120,
  "customer_id": 42,
  "debt_group_id": 1,
  "business_unit_id": 1,
  "status": "PENDING",
  "is_collectable": true,
  "is_contractable": true,
  "original_value": 1000.0,
  "today_value": 1078.5,
  "due_date": "2026-05-15",
  "origin_date": "2026-04-15",
  "external_id": "TIT-88213",
  "origin_contract_id": "767",
  "created_at": "2026-08-27T10:31:00Z",
  "updated_at": "2026-08-27T10:31:00Z"
}

A dívida nasce em PENDING e a régua de cobrança do grupo assume a partir daí.

4. Receba os eventos

A cobrança acontece do lado da Quyta. Para o seu sistema saber o que aconteceu — acordo fechado, parcela paga, dívida liquidada — cadastre um endpoint de webhook no painel.

Code
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "contract.installment.paid",
  "version": "1",
  "created_at": "2026-09-15T14:02:11Z",
  "data": { "...": "..." }
}

Os detalhes estão em Webhooks. Vale a pena configurá-los agora: sem eles, a única forma de saber que uma dívida foi paga é ficar consultando GET /debts em laço.

Conferindo o resultado

Para ver a dívida que você acabou de criar:

Code
curl -s "$QUYTA_API/debts?external_id=TIT-88213" \
  -H "Authorization: Bearer $QUYTA_TOKEN"

Ou toda a carteira ainda cobrável de um cliente:

Code
curl -s "$QUYTA_API/debts?customer_id=42&is_collectable=true" \
  -H "Authorization: Bearer $QUYTA_TOKEN"

Daqui para frente

• Sincronizando a carteira — carga inicial, atualizações diárias e volume.
• Tratamento de erros — o que fazer com cada código de resposta.
• Referência de API — todos os campos e validações de cada endpoint.