Plataformas parceiras
Estas rotas são para plataformas parceiras homologadas pelo Tesselys, que vendem algo em nome da empresa cliente e precisam registrar a conexão e os pedidos de contratação no Tesselys. Se você está integrando o seu próprio sistema, provavelmente não precisa delas.
As duas rotas usam a mesma autenticação do resto da API (veja Autenticação): o parceiro recebe da empresa cliente a API Key e o Secret, e a empresa é sempre a dona da chave. Nada no corpo da requisição diz de qual empresa é a conexão.
| Método | Rota | O que faz | Recurso do plano |
|---|---|---|---|
POST | /external/v1/integrations/:provider/connect | Registra o aperto de mão do parceiro | Webhooks e Integrações |
DELETE | /external/v1/integrations/:provider/connect | Desfaz o aperto de mão | Webhooks e Integrações |
POST | /external/v1/hiring-requests | Recebe um pedido de contratação | Contratos Recorrentes |
Aperto de mão
POST /external/v1/integrations/:provider/connect
O parceiro se apresenta informando a URL dele e o segredo com que o Tesselys vai assinar as chamadas de volta. :provider é o identificador do parceiro, em minúsculas, informado pelo Tesselys na homologação. Provedor sem aperto de mão responde 404.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
baseUrl | string | Sim | URL base pública (HTTPS) do parceiro. Endereços internos ou privados são recusados (400). |
webhookSecret | string | Sim | Segredo gerado pelo parceiro para esta conta, de 32 a 512 caracteres. O Tesselys assina com ele (HMAC-SHA256) o corpo de toda chamada de volta. Nunca é devolvido. Menos de 32 caracteres responde 400. |
accountRef | string | Não | Identificador da conta no parceiro (até 120 caracteres). |
accountName | string | Não | Nome da conta no parceiro, exibido na tela de integrações (até 120 caracteres). |
notificationEmail | string | Não | E-mail que recebe o aviso quando uma chamada de volta falhar em todas as tentativas. |
Resposta (200):
{
"companyKey": "acme",
"companyName": "ACME Serviços Ltda",
"provider": "NOME_DO_PROVEDOR",
"status": "DISCONNECTED",
"activatedAt": null
}
- A conexão nasce aguardando ativação (
status=DISCONNECTED): a empresa cliente precisa ativá-la no Marketplace do Tesselys. - Reenviar os mesmos dados não muda nada. URL ou segredo diferentes substituem os anteriores e a conexão volta a aguardar ativação.
- Um reenvio sem
accountRef,accountNameounotificationEmailmantém o valor já informado. companyKeyidentifica a empresa em toda chamada de volta.
DELETE /external/v1/integrations/:provider/connect
Desliga a integração do lado do Tesselys (as automações do provedor param). Use quando a chave de API da empresa for descadastrada no parceiro. Responde 200 com { "status": "DISCONNECTED" }.
Pedido de contratação
POST /external/v1/hiring-requests
Recebe um item contratado na plataforma parceira. O Tesselys:
- cria ou reaproveita o cliente e o signatário, pelo documento (CNPJ ou CPF);
- cria ou reaproveita o contrato do cliente, pela referência do cliente no parceiro (
contract.externalRef); - cria o item deste pedido no contrato.
O contrato nasce em rascunho e o item fica aguardando ativação. Nada é cobrado nem ativado nesta chamada.
A chamada é idempotente pelo item (externalSource + contractItem.externalRef): reenviar o mesmo pedido devolve os mesmos IDs com alreadyExisted: true.
Corpo:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
externalSource | string | Sim | Sistema de origem (até 40 caracteres). |
requestedBy | object | Não | Quem enviou o pedido no sistema de origem: name (opcional) e email (obrigatório no bloco). O e-mail recebe o aviso se o Tesselys não conseguir devolver a ativação ou a suspensão do item. |
customer | object | Sim | Cliente (quem contrata e paga). Campos abaixo. |
representative | object | Sim | Pessoa física que assina pelo cliente. Mesmos campos de customer, mais relation. Exige nome, CPF válido, data de nascimento e ao menos um e-mail. |
contract | object | Sim | Contrato do cliente. Campos abaixo. |
contractItem | object | Sim | O item contratado neste pedido. Campos abaixo. |
customer e representative:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
personType | string | Sim | COMPANY (CNPJ) ou INDIVIDUAL (CPF). O signatário é sempre pessoa física. |
name | string | Sim | Razão social (PJ) ou nome completo (PF). É o que sai na nota fiscal. |
socialName | string | Não | Nome fantasia. |
documentNumber | string | Sim | CNPJ ou CPF, só dígitos. Documento inválido responde 400. |
externalCode | string | Não | Identificador da pessoa no sistema de origem. |
birthDate | string | Não (Sim no signatário) | Data de nascimento, AAAA-MM-DD. |
addressMetadata | object | Não | Endereço (zipCode, street, streetNumber, complement, neighborhood, city, state, country). O código IBGE é resolvido pelo CEP. |
emails | object[] | Sim (ao menos um) | Lista de { "email": "...", "isMain": true }. O principal recebe nota e cobrança. |
phones | object[] | Não | Lista de { "phoneNumber": "41999999999", "countryCode": "55", "hasWhatsApp": true, "isMain": true }. |
relation | object | Não | Só no signatário: roleType (papel junto ao cliente) e jobTitle (cargo, texto livre). |
contract:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
externalRef | string | Sim | Referência do cliente no sistema de origem. Os próximos pedidos com a mesma referência entram no mesmo contrato. |
id | string | Não | ID de um contrato que já existe no Tesselys (cliente cadastrado fora da integração). O item entra nele, e o contrato passa a ser achado pelo externalRef nos próximos pedidos. |
title | string | Não | Título do contrato (só na criação). |
description | string | Não | Observações gerais (só na criação). |
startDate | string | Não | Início da vigência do contrato, AAAA-MM-DD (só na criação). |
contractItem:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
externalRef | string | Sim | Referência do item no sistema de origem. É a chave de idempotência. |
id | string | Não | ID de um item que já existe no Tesselys. O pedido só vincula a referência ao item; valor, vigência e descrição não mudam. |
description | string | Sim para item novo | Descrição do item. |
unitPrice | number | Sim para item novo | Valor mensal do item, em reais (maior que zero). |
startDate | string | Sim para item novo | Início da vigência do item, AAAA-MM-DD. |
endDate | string | Não | Fim da vigência, AAAA-MM-DD. Sem ele, o item vale até ser encerrado. |
quantity | number | Não | Quantidade (não é número de cobranças). |
metadata | object | Não | Dados da origem. Pode levar billingPreference (paymentMethod, firstDueDate, notes), só informativo: não gera cobrança. |
Resposta (200):
{
"customer": { "id": "…" },
"representative": { "id": "…" },
"contract": { "id": "…", "code": "CT-000123", "status": "DRAFT" },
"contractItem": { "id": "…", "activatedAt": null },
"alreadyExisted": false
}
Erros específicos:
| Status | Quando |
|---|---|
400 | Faltam externalSource, contract.externalRef ou contractItem.externalRef; cliente sem nome, com documento inválido ou sem e-mail; signatário incompleto; item novo sem descrição, sem valor, sem início ou com fim antes do início. |
404 | contract.id ou contractItem.id não existe nesta empresa (ou o item já foi encerrado). |
409 | O item ou o contrato informado já está ligado a outra referência externa, ou o cliente já tem outro contrato com a mesma referência. |
422 | O item informado não é do contrato informado, o contrato é de outro cliente (documento diferente) ou o contrato já terminou e não recebe itens. |
A nossa equipe ajuda você a configurar e usar esse recurso.