Ambientes de teste (Sandbox)

Isole o seu desenvolvimento, experimente sem medo e limpe os seus dados com um único clique.

Por que usar ambientes de teste?

Ao integrar APIs financeiras, é essencial testar a lógica da sua aplicação sem gerar transações reais nem enviar e-mails para clientes de verdade. O Cord resolve isso oferecendo a você um ambiente de teste (Sandbox) completamente isolado.

Os dados criados no modo de teste (orçamentos, clientes, webhooks) nunca interagem com os seus dados em produção.

Como identificar o modo de teste

No painel: quando o modo de teste está ativo, você vê um indicador visual laranja na interface. Todas as ações manuais que você realizar acontecem dentro do ambiente isolado.
Na API: as chaves de API secretas determinam automaticamente qual ambiente você está chamando. Uma chave de teste interage com o Sandbox, enquanto uma chave de produção toca os seus dados reais.

Importante: nunca use chaves reais nos seus testes unitários ou de integração.

Reinício rápido (Sandbox Reset)

Durante o desenvolvimento de integrações, você vai gerar com frequência milhares de registros descartáveis. O Cord tem uma ferramenta radical para devolver o seu ambiente a um estado limpo: o endpoint de reset.

Esvaziar os dados do ambiente de teste

Você pode invocar uma limpeza destrutiva (que exclui em cascata clientes, orçamentos, produtos e eventos do ambiente de teste) fazendo um POST para o seguinte endpoint interno (exige uma sessão ativa no navegador no modo de teste):

POST /api/test-mode/reset

Atenção: Este endpoint tem proteções de banco de dados rígidas (sandbox_of is not null). Mesmo que você o chame por engano no seu ambiente de produção, o banco de dados aborta a transação para proteger os seus dados reais. Ele só funciona dentro de ambientes Sandbox.

Simuladores (test helpers)

Com uma chave sk_test_, você pode provocar o que em produção é feito por um terceiro: o SAT respondendo, o tempo passando ou o cliente abrindo o link. Cada simulador percorre o mesmo código de produção, então os webhooks, o histórico e os e-mails saem iguais aos de produção. Com uma chave de produção, eles respondem test_mode_only, e o banco de dados rejeita qualquer simulação sobre uma organização real.

Forçar o resultado da próxima timbragem

curl -X POST https://cordhq.app/api/v1/test_helpers/fiscal \
  -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \
  -d '{ "siguiente_resultado": "pac_caido" }'

Resultados: exito, pac_caido (a fatura fica como rascunho e pode ser tentada de novo), receptor_invalido, certificado_vencido e timbre_duplicado. Ele é consumido na próxima emissão; sem nenhum pendente, a emissão simulada é bem-sucedida.

Simular o cliente e o tempo

curl -X POST https://cordhq.app/api/v1/test_helpers/cotizaciones/8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10 \
  -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \
  -d '{ "accion": "vista" }'

vista registra a abertura pelo cliente (quote.viewed) e vencer faz o orçamento expirar (quote.expired). Aprovar, recusar e marcar como pago já estão em POST /api/v1/cotizaciones/{id}.

Disparar um webhook

curl -X POST https://cordhq.app/api/v1/test_helpers/webhooks \
  -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \
  -d '{ "evento": "quote.approved", "objeto_id": "8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10" }'

Aceita qualquer um dos eventos do catálogo. Com o objeto_id de um orçamento ou de uma fatura de teste, usa os dados reais deles; sem ele, dados de exemplo com ids test_…. O objeto_id deve ser do tipo do evento: um orçamento para quote.*, payment.*, invoice.stamped e invoice.issued, e uma fatura para os demais invoice.*. Nos eventos de clientes, produtos, tarefas, promessas, contestações, reembolsos, repasses e conta, são sempre usados dados de exemplo. A entrega passa pelo outbox real: assinatura, novas tentativas e histórico nas entregas do endpoint, na aba Webhooks do Cord Workbench. Com objeto_id, o evento também fica no histórico de eventos e na aba Eventos; com dados de exemplo, não, porque não é um evento do seu negócio.