Garantify

Garantify API

Documentação completa para integrar seu sistema com a plataforma Garantify. Emita certificados de garantia digital, gerencie clientes e receba notificações em tempo real.

Autenticação

Inclua o header X-Garantify-API-Key em todas as requisições. Gerencie suas chaves no painel da Garantify Enterprise. Para sandbox, use uma chave grtf_test_. O endereço da API é o mesmo.

URL Base da API

http://localhost:5050

Certificados

Emitir, listar, consultar e cancelar certificados de garantia digital.

Emite um novo certificado de garantia digital. **Endpoint assíncrono** — retorna **202 Accepted** com `taskId` e o processamento real (validação de produto/cliente, persistência, envio de e-mail) ocorre em segundo plano. Inscreva-se no webhook `certificate.created` para ser notificado quando o certificado for emitido com sucesso, ou em `task.failed` para falhas.

Parâmetros do Request

CampoTipoObrigatórioDescrição
produtoIdstringSimID do produto cadastrado
clienteIdstringNãoID do cliente já cadastrado (opcional, usa dados do cliente)
consumidorNomestringNãoNome do consumidor. OBRIGATÓRIO quando clienteId não é informado.
consumidorEmailstringNãoE-mail do consumidor. Opcional. Se informado, deve ser um endereço válido e será usado para enviar o certificado por e-mail (se habilitado). Sem e-mail, o certificado é criado normalmente mas sem envio automático.
consumidorTelefonestringNãoTelefone do consumidor
garantiaMesesnumberNãoDuração da garantia em meses. Se omitido, usa o garantiaMeses cadastrado no produto.
observacaostringNãoObservação livre
vendedorNomestringNãoNome do vendedor
vendedorEmailstringNãoE-mail do vendedor
vendedorTelefonestringNãoTelefone do vendedor
metadataobjectNãoDados adicionais em formato chave-valor
dataEmissaostring (ISO 8601)NãoData de emissão do certificado em formato ISO 8601 (ex: "2026-03-21T00:00:00Z"). Opcional. Útil para backfill de vendas anteriores ou para alinhar a emissão com a data fiscal da venda. Se omitido, usa a data/hora atual (UTC). Limites: não pode estar no futuro nem antes de 10 anos atrás.

Exemplo de Request Body

{
  "produtoId": "d5e6f7a8-9012-3cde-f456-7890abcdef01",
  "clienteId": "c4d5e6f7-8901-2bcd-ef34-567890abcdef",
  "garantiaMeses": 12,
  "observacao": "Presente de aniversário",
  "vendedorNome": "João Silva",
  "vendedorEmail": "joao@joalheria.com",
  "metadata": {
    "lojaId": "loja-sp-01"
  },
  "dataEmissao": "2026-03-15T12:00:00Z"
}

Resposta de Sucesso200

{
  "taskId": "task_3fa85f645717456...",
  "status": "Pending",
  "criadoEm": "2026-03-21T12:00:00Z"
}

Resposta de Erro404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Produto não encontrado."
  }
}

Exemplo de Código

curl -X POST "http://localhost:5050/api/v1/certificados" \
  -H "X-Garantify-API-Key: SUA_API_KEY" \
  -H "X-Garantify-Operador-Id: ID_DO_OPERADOR" \
  -H "Content-Type: application/json" \
  -d '{
    "produtoId": "d5e6f7a8-9012-3cde-f456-7890abcdef01",
    "clienteId": "c4d5e6f7-8901-2bcd-ef34-567890abcdef",
    "garantiaMeses": 12,
    "observacao": "Presente de aniversário",
    "vendedorNome": "João Silva",
    "vendedorEmail": "joao@joalheria.com",
    "metadata": { "lojaId": "loja-sp-01" }
  }'

Emite múltiplos certificados de garantia em uma única chamada. Cada produto pode ter uma quantidade (cada unidade gera um certificado individual). Se o consumidor possui e-mail cadastrado, envia 1 e-mail consolidado; sem e-mail o lote é criado normalmente sem envio. Máximo de 200 itens por lote. **Endpoint assíncrono** — retorna **202 Accepted** com `taskId`. O processamento real ocorre em segundo plano. Webhooks disparados durante o processamento: um evento `certificate.created` para cada certificado emitido (se o lote gerar N certificados, serão N eventos individuais) + um evento consolidado `certificates.batch_created` com todos os certificados do lote. Em caso de falha do worker, é disparado o webhook `task.failed`. Integrações que escutam `certificate.created` recebem a mesma granularidade da emissão unitária.

Parâmetros do Request

CampoTipoObrigatórioDescrição
consumidorIdstringSimID do consumidor (cliente) já cadastrado
produtosarraySimLista de produtos (mín: 1, máx: 200 itens)
produtos[].produtoIdstringSimID do produto cadastrado
produtos[].quantidadenumberNãoQuantidade de unidades do produto (padrão: 1, máx: 100). Cada unidade gera um certificado individual.
produtos[].observacaostringNãoObservação específica para os certificados deste produto
notaFiscalstringNãoNúmero da nota fiscal (máx: 100 caracteres)
metadataobjectNãoDados adicionais em formato chave-valor
vendedorNomestringNãoNome do vendedor (revendedor/representante) responsável pela venda. Aplicado a todos os certificados do lote.
vendedorEmailstringNãoE-mail do vendedor (opcional, validado como endereço válido se fornecido).
vendedorTelefonestringNãoTelefone do vendedor (formato livre, sem validação).
dataEmissaostring (ISO 8601)NãoData de emissão aplicada a todos os certificados do lote em formato ISO 8601 (ex: "2026-03-21T00:00:00Z"). Opcional. Útil para backfill de vendas anteriores ou para alinhar a emissão com a data fiscal da venda. Se omitido, usa a data/hora atual (UTC). Limites: não pode estar no futuro nem antes de 10 anos atrás.

Exemplo de Request Body

{
  "consumidorId": "c4d5e6f7-8901-2bcd-ef34-567890abcdef",
  "produtos": [
    {
      "produtoId": "d5e6f7a8-9012-3cde-f456-7890abcdef01",
      "quantidade": 2,
      "observacao": "Presente de aniversário"
    },
    {
      "produtoId": "a1b2c3d4-5678-9abc-def0-123456789abc",
      "quantidade": 1
    },
    {
      "produtoId": "e5f6a7b8-9012-3cde-f456-abcdef012345",
      "quantidade": 3,
      "observacao": "Edição limitada"
    }
  ],
  "notaFiscal": "NF-001234",
  "metadata": {
    "lojaId": "loja-sp-01",
    "vendedora": "Ana"
  },
  "vendedorNome": "Karla Franciane",
  "vendedorEmail": "karla@loja.com.br",
  "vendedorTelefone": "+5547999999999",
  "dataEmissao": "2026-03-15T12:00:00Z"
}

Resposta de Sucesso200

{
  "taskId": "task_4fb96g756828567...",
  "status": "Pending",
  "criadoEm": "2026-03-21T12:00:00Z"
}

Resposta de Erro404

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Limite mensal de 500 certificados seria excedido. Atual: 498, solicitado: 3. Faça upgrade do plano."
  }
}

Exemplo de Código

curl -X POST "http://localhost:5050/api/v1/certificados/lote" \
  -H "X-Garantify-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consumidorId": "c4d5e6f7-8901-2bcd-ef34-567890abcdef",
    "produtos": [
      { "produtoId": "d5e6f7a8-9012-3cde-f456-7890abcdef01", "quantidade": 2, "observacao": "Presente de aniversário" },
      { "produtoId": "a1b2c3d4-5678-9abc-def0-123456789abc", "quantidade": 1 },
      { "produtoId": "e5f6a7b8-9012-3cde-f456-abcdef012345", "quantidade": 3, "observacao": "Edição limitada" }
    ],
    "notaFiscal": "NF-001234",
    "metadata": { "lojaId": "loja-sp-01", "vendedora": "Ana" }
  }'

Lista certificados com paginação por página (offset). Suporta filtros por status, busca textual e metadata.

Parâmetros do Request

CampoTipoObrigatórioDescrição
pagenumberNãoNúmero da página, começando em 1 (padrão: 1)
pageSizenumberNãoItens por página (padrão: 20, máx: 200)
statusstringNãoFiltrar por status: Ativa, Expirada, Cancelada
searchstringNãoBusca por código do certificado, nome do cliente, e-mail, produto ou marca
operadorIdstringNãoFiltrar certificados emitidos por um operador específico (UUID do operador)
metadata.*stringNãoFiltrar por metadata (match exato). Vírgula = OR (metadata.vendedora=Karla,Joana). Não suporta operador "contém".

Resposta de Sucesso200

{
  "total": 142,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8,
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "codigoCertificado": "GF-202603-A7K3M9",
      "consumidorNome": "Carlos Souza",
      "consumidorEmail": "carlos@email.com",
      "produtoNome": "Anel Ouro 18k",
      "marcaNome": "Vivara",
      "emissorId": "d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8",
      "emissorNome": "João Silva",
      "emissorTipo": "Operador",
      "status": "Ativa",
      "dataEmissao": "2026-03-21T00:00:00Z",
      "dataExpiracao": "2027-03-21T00:00:00Z",
      "metadata": {}
    }
  ]
}

Exemplo de Código

curl -X GET "http://localhost:5050/api/v1/certificados?status=Ativa&search=Maria&metadata.vendedora=Karla&page=1&pageSize=20" \
  -H "X-Garantify-API-Key: SUA_API_KEY"

Busca um certificado específico pelo seu ID (UUID).

Resposta de Sucesso200

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "codigoCertificado": "GF-202603-A7K3M9",
  "clienteId": "c4d5e6f7-8901-2bcd-ef34-567890abcdef",
  "clienteNome": "Carlos Souza",
  "clienteEmail": "carlos@email.com",
  "clienteTelefone": "11999887766",
  "produtoId": "d5e6f7a8-9012-3cde-f456-7890abcdef01",
  "produtoNome": "Anel Ouro 18k",
  "produtoCodigo": "ANL-001",
  "marcaNome": "Vivara",
  "vendedorNome": "João Silva",
  "vendedorEmail": "joao@joalheria.com",
  "emissorId": "d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8",
  "emissorNome": "João Silva",
  "emissorTipo": "Operador",
  "status": "Ativa",
  "statusEfetivo": "Ativa",
  "observacao": "Presente de aniversário",
  "dataEmissao": "2026-03-21T00:00:00Z",
  "dataExpiracao": "2027-03-21T00:00:00Z",
  "metadata": {
    "lojaId": "loja-sp-01"
  }
}

Resposta de Erro404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Certificado não encontrado."
  }
}

Exemplo de Código

curl -X GET "http://localhost:5050/api/v1/certificados/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Garantify-API-Key: SUA_API_KEY"

Busca um certificado pelo código de certificado (ex: GF-202603-A7K3M9).

Resposta de Sucesso200

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "codigoCertificado": "GF-202603-A7K3M9",
  "clienteNome": "Carlos Souza",
  "clienteEmail": "carlos@email.com",
  "produtoNome": "Anel Ouro 18k",
  "marcaNome": "Vivara",
  "emissorId": "d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8",
  "emissorNome": "João Silva",
  "emissorTipo": "Operador",
  "status": "Ativa",
  "statusEfetivo": "Ativa",
  "dataEmissao": "2026-03-21T00:00:00Z",
  "dataExpiracao": "2027-03-21T00:00:00Z",
  "metadata": {}
}

Exemplo de Código

curl -X GET "http://localhost:5050/api/v1/certificados/codigo/GF-202603-A7K3M9" \
  -H "X-Garantify-API-Key: SUA_API_KEY"

Cancela um certificado de garantia ativo. A operação é irreversível. **Endpoint assíncrono** — retorna **202 Accepted** com `taskId`. O cancelamento real ocorre em segundo plano. Inscreva-se no webhook `certificate.cancelled` para confirmação ou `task.failed` para falhas.

Parâmetros do Request

CampoTipoObrigatórioDescrição
motivostringNãoMotivo do cancelamento

Exemplo de Request Body

{
  "motivo": "Produto devolvido pelo consumidor"
}

Resposta de Sucesso200

{
  "taskId": "task_5gc07h867939678...",
  "status": "Pending",
  "criadoEm": "2026-03-21T12:00:00Z"
}

Exemplo de Código

curl -X POST "http://localhost:5050/api/v1/certificados/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancelar" \
  -H "X-Garantify-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "Produto devolvido pelo consumidor"
  }'

Cancela múltiplos certificados em uma única chamada (até 200 itens). Aceita IDs (UUID) ou códigos (ex: SBSRL-XXXXXXXXXX). Certificados já cancelados ou expirados são ignorados silenciosamente. A operação é irreversível para os certificados cancelados. **Endpoint assíncrono** — retorna **202 Accepted** com `taskId`. O processamento ocorre em segundo plano. Webhooks: um evento `certificate.cancelled` é despachado para cada certificado cancelado com sucesso. Em caso de falha do worker, é disparado `task.failed`.

Parâmetros do Request

CampoTipoObrigatórioDescrição
certificadosstring[]SimLista de IDs (UUID) ou códigos de certificado a cancelar. Máximo 200 itens. Aceita mistura — cada item é detectado como UUID ou código.
motivostringNãoMotivo do cancelamento aplicado a todos os certificados do lote.

Exemplo de Request Body

{
  "certificados": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "GF-202603-A7K3M9",
    "GF-202603-B8L4N0"
  ],
  "motivo": "Lote devolvido pelo varejo"
}

Resposta de Sucesso200

{
  "taskId": "task_6hd18i977a4078...",
  "status": "Pending",
  "criadoEm": "2026-03-21T12:00:00Z"
}

Exemplo de Código

curl -X POST "http://localhost:5050/api/v1/certificados/cancelar-lote" \
  -H "X-Garantify-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "certificados": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "GF-202603-A7K3M9"
    ],
    "motivo": "Lote devolvido pelo varejo"
  }'

Transfere um certificado de garantia para outro consumidor. É obrigatório informar pelo menos um identificador (email ou novoConsumidorId).

Parâmetros do Request

CampoTipoObrigatórioDescrição
emailstringNãoE-mail do novo proprietário. Obrigatório se novoConsumidorId não for informado.
novoConsumidorIdstringNãoID do novo consumidor já cadastrado. Obrigatório se email não for informado.

Exemplo de Request Body

{
  "email": "novo-proprietario@email.com"
}

Resposta de Sucesso200

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "codigoCertificado": "GF-202603-A7K3M9",
  "status": "Ativa",
  "transferidoPara": "a1b2c3d4-5678-9abc-def0-123456789abc"
}

Exemplo de Código

curl -X POST "http://localhost:5050/api/v1/certificados/3fa85f64-5717-4562-b3fc-2c963f66afa6/transferir" \
  -H "X-Garantify-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo-proprietario@email.com"
  }'

Anexa uma nota fiscal a um certificado de garantia. A chave da nota fiscal deve ser obtida via upload de imagem.

Parâmetros do Request

CampoTipoObrigatórioDescrição
notaFiscalKeystringSimChave S3 da imagem da nota fiscal (obtida via POST /upload/imagem)

Exemplo de Request Body

{
  "notaFiscalKey": "enterprise/b2c3d4e5/nota-fiscal.jpg"
}

Resposta de Sucesso200

{
  "message": "Nota fiscal atualizada com sucesso."
}

Exemplo de Código

curl -X PATCH "http://localhost:5050/api/v1/certificados/3fa85f64-5717-4562-b3fc-2c963f66afa6/nota-fiscal" \
  -H "X-Garantify-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notaFiscalKey": "enterprise/b2c3d4e5/nota-fiscal.jpg"
  }'

Remove a nota fiscal anexada a um certificado de garantia.

Resposta de Sucesso200

{
  "message": "Nota fiscal removida com sucesso."
}

Exemplo de Código

curl -X DELETE "http://localhost:5050/api/v1/certificados/3fa85f64-5717-4562-b3fc-2c963f66afa6/nota-fiscal" \
  -H "X-Garantify-API-Key: SUA_API_KEY"

Envia o e-mail do certificado de garantia para o consumidor associado.

Resposta de Sucesso200

{
  "message": "E-mail do certificado enviado com sucesso.",
  "enviado": true
}

Exemplo de Código

curl -X POST "http://localhost:5050/api/v1/certificados/3fa85f64-5717-4562-b3fc-2c963f66afa6/enviar-email" \
  -H "X-Garantify-API-Key: SUA_API_KEY"