# API da Nock

A API da Nock é acessível publicamente pela internet, mas as operações que usam dados ou créditos são autenticadas. O acesso está em beta e é liberado por convite.

- Base URL: `https://api.usenock.com`
- OpenAPI 3.1: [https://api.usenock.com/openapi.json](https://api.usenock.com/openapi.json)
- Autenticação: `Authorization: Bearer $NOCK_API_KEY`
- Formato: JSON

Crie e revogue chaves na página **API** do painel. Nunca exponha uma chave no navegador ou em um repositório.

As mesmas operações estão disponíveis no servidor MCP da Nock (`https://api.usenock.com/mcp`) e para o Nock Agent, sobre o mesmo registro de ferramentas e o mesmo modelo de créditos.

## GET /health

### Verificar disponibilidade

Confirma que a API está respondendo. Não exige autenticação.

```bash
curl -X GET "https://api.usenock.com/health"
```

## GET /api/providers

### Listar provedores

Lista provedores, capacidades e campos de enriquecimento disponíveis. Não exige autenticação.

```bash
curl -X GET "https://api.usenock.com/api/providers"
```

## POST /api/sourcing/people

### Buscar pessoas

Encontra profissionais por cargo, função, senioridade, empresa, setor, tecnologia, faturamento ou localização. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X POST "https://api.usenock.com/api/sourcing/people" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "jobTitle": "Head of Sales",
  "seniorities": [
    "head",
    "director"
  ],
  "technologies": [
    "salesforce"
  ],
  "companyLocation": "Brazil",
  "limit": 10
}'
```

## POST /api/companies/search

### Buscar empresas

Encontra empresas por setor, palavras-chave, tamanho e localização; no Brasil, converte atividades conhecidas em CNAEs e aceita filtros cadastrais, societários e de contato. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X POST "https://api.usenock.com/api/companies/search" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "keywords": [
    "BPO financeiro"
  ],
  "cnaes": [
    "6920601"
  ],
  "registrationStatuses": [
    "ATIVA"
  ],
  "legalNatureCodes": [
    "2062"
  ],
  "simpleOption": true,
  "openingDateMin": "2020-01-01",
  "hasPhone": true,
  "state": "PR",
  "city": "Curitiba",
  "limit": 10
}'
```

## POST /api/enrich

### Enriquecer dados

Completa uma pessoa ou empresa a partir dos identificadores disponíveis. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X POST "https://api.usenock.com/api/enrich" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "fullName": "Ada Lovelace",
  "companyDomain": "example.com",
  "goalFields": [
    "work_email"
  ]
}'
```

## POST /api/research

### Pesquisar na web

Responde uma pergunta usando os campos enviados como contexto da linha. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X POST "https://api.usenock.com/api/research" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "prompt": "Resuma em uma frase o que a empresa faz.",
  "company": "Nock",
  "companyDomain": "usenock.com",
  "webSearch": true
}'
```

## POST /api/ai-column

### Gerar com IA

Gera um valor curto com uma instrução e quaisquer campos string como contexto. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X POST "https://api.usenock.com/api/ai-column" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "instruction": "Classifique como Enterprise, Mid-market ou SMB.",
  "company": "Acme",
  "employees": "480"
}'
```

## GET /api/prospecting/templates

### Listar templates de prospecção

Retorna as configurações reutilizáveis de oferta, remetente, tom e contexto da empresa. Não consome créditos. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X GET "https://api.usenock.com/api/prospecting/templates" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## POST /api/prospecting/templates

### Criar ou atualizar um template

Salva um template pelo nome: usar um nome existente atualiza aquele template em vez de duplicá-lo. Não consome créditos. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X POST "https://api.usenock.com/api/prospecting/templates" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Padrão Nock",
  "offering": "Enriquecimento de dados B2B com cascata de provedores",
  "senderName": "Ana",
  "tone": "direto e consultivo",
  "language": "Português (Brasil)"
}'
```

## PATCH /api/prospecting/templates/{templateId}

### Atualizar um template

Única forma de renomear um template. Campos omitidos mantêm o valor atual. Não consome créditos. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X PATCH "https://api.usenock.com/api/prospecting/templates/{templateId}" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "tone": "direto e consultivo"
}'
```

## DELETE /api/prospecting/templates/{templateId}

### Excluir um template

Remove o template. As campanhas já criadas com ele não são afetadas. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X DELETE "https://api.usenock.com/api/prospecting/templates/{templateId}" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## GET /api/prospecting/campaigns

### Listar campanhas de prospecção

Retorna cada campanha com o total de prospecções por etapa do pipeline. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X GET "https://api.usenock.com/api/prospecting/campaigns" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## POST /api/prospecting/campaigns

### Criar campanha de prospecção

Cria um rascunho com nome e oferta. Opcionalmente gera e-mail e nota de LinkedIn por pessoa selecionada em uma planilha. A configuração pode vir de um templateId, dos campos enviados ou de ambos. Não consome créditos. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X POST "https://api.usenock.com/api/prospecting/campaigns" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Fintechs SP",
  "offering": "Enriquecimento de dados B2B"
}'
```

## GET /api/prospecting/campaigns/{campaignId}

### Detalhar uma campanha

Retorna a configuração da campanha e todas as suas prospecções. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X GET "https://api.usenock.com/api/prospecting/campaigns/{campaignId}" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## PATCH /api/prospecting/campaigns/{campaignId}

### Atualizar uma campanha

Altera o nome, a oferta, o tom, o remetente ou o contexto da campanha. Campos omitidos permanecem iguais. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X PATCH "https://api.usenock.com/api/prospecting/campaigns/{campaignId}" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "offering": "Enriquecimento de dados B2B"
}'
```

## POST /api/prospecting/campaigns/{campaignId}/prospects

### Adicionar pessoas a uma campanha

Gera mensagens para até 25 pessoas de uma planilha e as vincula à campanha. Linhas já presentes são ignoradas. Não consome créditos. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X POST "https://api.usenock.com/api/prospecting/campaigns/{campaignId}/prospects" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "sheetId": "0f5b3b3e-8a1f-4a67-9d0d-2b6f5f0f1a11",
  "rowIds": [
    "row-1",
    "row-2"
  ]
}'
```

## GET /api/prospecting/prospects

### Listar prospecções

Retorna as pessoas com mensagem gerada. Aceita os filtros campaignId e status. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X GET "https://api.usenock.com/api/prospecting/prospects" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## GET /api/prospecting/prospects/{prospectId}

### Detalhar uma prospecção

Retorna a mensagem completa, o contexto capturado da planilha e a etapa atual. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X GET "https://api.usenock.com/api/prospecting/prospects/{prospectId}" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## PATCH /api/prospecting/prospects/{prospectId}

### Atualizar etapa ou mensagem

Move a prospecção no pipeline e/ou reescreve a mensagem. Editar não regenera nada e não consome créditos. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X PATCH "https://api.usenock.com/api/prospecting/prospects/{prospectId}" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "status": "awaiting_reply"
}'
```

## DELETE /api/prospecting/prospects/{prospectId}

### Excluir uma prospecção

Remove a pessoa, a mensagem e o histórico. A campanha permanece mesmo se ficar sem pessoas. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X DELETE "https://api.usenock.com/api/prospecting/prospects/{prospectId}" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## GET /api/prospecting/prospects/{prospectId}/events

### Histórico de uma prospecção

Retorna criação, edições de mensagem e mudanças de etapa em ordem cronológica. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X GET "https://api.usenock.com/api/prospecting/prospects/{prospectId}/events" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## GET /api/credits

### Consultar créditos

Retorna o saldo, consumo total e os movimentos mais recentes. Exige uma chave de API no header `Authorization: Bearer <chave>`.

```bash
curl -X GET "https://api.usenock.com/api/credits" \
  -H "Authorization: Bearer $NOCK_API_KEY"
```

## Erros

- `400`: parâmetros inválidos
- `401`: chave ausente, inválida ou revogada
- `402`: saldo de créditos insuficiente
- `429`: limite de requisições excedido

Esta é uma API beta. Os endpoints documentados são a superfície pública inicial; mudanças incompatíveis serão comunicadas antes de entrarem em vigor.