Guia · sistemas da Urso Pardo

Venda já paga em outro sistema

O cliente paga no seu sistema. O Cuidaro registra a receita, dá a baixa na conta escolhida pela empresa, emite a NFS-e e avisa por webhook. Seu sistema não envia nenhum dado fiscal: código do serviço, alíquotas e NBS vêm do catálogo do Cuidaro.

Sequência

1. Uma vezGET /services — escolha o serviço do catálogo e guarde o id.
2. Venda pagaPOST /contacts — cliente pelo CPF/CNPJ, com endereço e IBGE.
3. Venda pagaPOST /service-orders — OS com service_id e external_reference do pedido.
4. Venda pagaPOST …/invoice — settlement.type = external; a NFS-e é pedida em seguida.
5. Avisofiscal_invoice.issued — número da nota e link do PDF.
6. EstornoPOST …/cancel — estorna a baixa e pede o cancelamento da nota.
7. Avisofiscal_invoice.cancelled ou cancellation_rejected.

Regras que evitam problema

• Nunca fixe ids no código. Guarde o service_id da empresa e confira nfse_ready.
• external_reference é única por empresa. Se a resposta da criação se perder, repetir devolve 409 RESOURCE_ALREADY_EXISTS com existing_resource_id.
• settlement.amount precisa ser igual ao centavo ao total da OS. O mesmo pagamento (gateway + gateway_reference) não quita duas OS.
• Faturar e cancelar são operações de idempotência estrita: se a resposta se perder, consulte a OS antes de tentar de novo.
• A NFS-e é assíncrona. Se não puder nem ser iniciada, a OS continua faturada e o motivo vem em meta.warnings.

Estorno antes do faturamento

O cancel também vale para OS ainda não faturada: responde 202 com status = cancelled e fiscal = null. Este comportamento é contrato.

NFS-e recusada

A recusa não desfaz o faturamento: a OS continua invoiced e a nota fica fiscal.status = rejected. Não há webhook de recusa. A empresa corrige o cadastro e reemite pela tela da OS no Cuidaro; a API não reemite. Quando a nova tentativa for autorizada, sai o fiscal_invoice.issued. Veja Problemas comuns.