Referência da API
API Pública do Geodocs
API REST com autenticação por Token de Acesso Pessoal (PAT) para automação de projetos GIS.
API:https://api.geodocs.io
Geo-API:https://geo-api.geodocs.io
Autenticação
Todas as requisições exigem um Token de Acesso Pessoal (PAT) no header Authorization. Crie tokens em Geodocs > Configurações > Tokens de API.
Formato do token:
gdx_<48 hex chars>Header da requisição:
Authorization: Bearer gdx_...Limite de requisições: 100 por minuto por token
Cada token possui escopos que controlam quais endpoints ele pode acessar.
# Autenticar com PAT
curl -H "Authorization: Bearer gdx_a1b2c3..." \
https://api.geodocs.io/api/public/v1/folders
Paginação
Todos os endpoints de listagem suportam paginação com estes parâmetros:
pageNúmero da página (padrão: 1)limitItens por página (padrão: 50, máximo: 100)termTermo de busca/filtroEnvelope da resposta
{
"content": [{ ... }],
"total": 142,
"page": 1,
"size": 50,
"pages": 3
}
"content": [{ ... }],
"total": 142,
"page": 1,
"size": 50,
"pages": 3
}
Endpoints
Folders
Escopo:
READ_FOLDERGET
/api/public/v1/foldersGET
/api/public/v1/folders/:keyAssignments
Escopo:
READ_ASSIGNMENTGET
/api/public/v1/assignmentsGET
/api/public/v1/assignments/:keyExpenses
Escopo:
READ_EXPENSEGET
/api/public/v1/expensesGET
/api/public/v1/expenses/:keyBudgets
Escopo:
READ_BUDGETGET
/api/public/v1/budgetsGET
/api/public/v1/budgets/:keyStatuses
Escopo: Nenhum escopo necessário
GET
/api/public/v1/statusesWebhooks
Escopo:
MANAGE_WEBHOOKPOST
/api/public/v1/webhooks/endpointsDELETE
/api/public/v1/webhooks/endpoints/:keyLayers
geo-apiEscopo: Nenhum escopo necessário
GET
/api/public/v1/layersGET
/api/public/v1/layers/:id/mvt/{z}/{x}/{y}Geometries
geo-apiEscopo: Nenhum escopo necessário
POST
/api/public/v1/geometries/geojsonEventos de Webhook
Quando inscrito, o Geodocs envia requisições HTTP POST para seu endpoint com este payload:
Tipos de evento disponíveis
folder.createdfolder.updatedfolder.deletedfolder.archivedassignment.createdassignment.updatedassignment.deletedexpense.createdexpense.updatedexpense.deletedbudget.createdbudget.updatedbudget.deletedPayload do evento
{
"id": "delivery-uuid",
"event": "folder.created",
"workspaceKey": "workspace-uuid",
"occurredAt": "2026-03-28T14:22:00Z",
"data": { "id": "entity-uuid", ... }
}
"id": "delivery-uuid",
"event": "folder.created",
"workspaceKey": "workspace-uuid",
"occurredAt": "2026-03-28T14:22:00Z",
"data": { "id": "entity-uuid", ... }
}
Verificação de assinatura
Cada entrega inclui um header X-Geodocs-Signature. Verifique usando HMAC-SHA256:
// Node.js
const crypto = require('crypto');
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
const received = header
.replace('sha256=', '');
const valid = crypto
.timingSafeEqual(
Buffer.from(expected),
Buffer.from(received));
Tratamento de Erros
Todos os endpoints retornam códigos HTTP padrão:
200OK204No Content (DELETE)400Bad Request401Unauthorized403Forbidden (missing scope)404Not Found429Too Many Requests500Internal Server ErrorFormato da resposta de erro
{
"statusCode": 403,
"message": "Token missing required scope: READ_FOLDER",
"error": "Forbidden"
}
"statusCode": 403,
"message": "Token missing required scope: READ_FOLDER",
"error": "Forbidden"
}