Integración v1

Esta página es pública. Un ERP u otra plataforma autentica con una API key orb_… emitida para un solo tenant. El tenant sale del secreto, nunca del body.

Réplica en el repositorio: docs/integracion.md.

1. Base URL

https://orbi.orbitrack.us

Las rutas de producto viven en /api/v1.

2. Autenticación

Authorization: Bearer orb_…

Orbi hashea la key (SHA-256) y carga el tenant asociado. No envíes tenant_id en el JSON. Una key de la organización A no puede leer datos de B.

3. Cómo obtener la key

• Superadmin: /platform → Organizaciones → Generar API key.
• Admin del tenant: POST /api/v1/api-keys (scope keys:manage).

El secreto solo viaja en el 201. Después solo verás el prefijo.

4. Scopes

5. Errores

{ "error": { "code": "forbidden", "message": "…" } }

Códigos habituales: unauthorized, forbidden, tenant_suspended, invalid_body, not_found, rate_limited.

6. Crear y listar un activo

curl -sS https://orbi.orbitrack.us/api/v1/assets \
  -H "Authorization: Bearer $ORBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_serial_id": "ERP-10042",
    "serial_number": "SN-10042",
    "asset_type": "compressor"
  }'

curl -sS "https://orbi.orbitrack.us/api/v1/assets?q=ERP-10042" \
  -H "Authorization: Bearer $ORBI_KEY"

7. Foto de catálogo

Tres pasos: URL firmada → PUT al Blob privado → complete (202).

curl -sS https://orbi.orbitrack.us/api/v1/assets/$ASSET_ID/images/upload-url \
  -H "Authorization: Bearer $ORBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slot":1,"mime_type":"image/jpeg"}'

curl -sS -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @foto.jpg

curl -sS https://orbi.orbitrack.us/api/v1/assets/$ASSET_ID/images/complete \
  -H "Authorization: Bearer $ORBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slot":1,"object_key":"'"$OBJECT_KEY"'","idempotency_key":"img-erp-1"}'

8. Verify 1:1

Sube la consulta con POST /api/v1/objects/query-upload-url, luego verify y haz poll a GET /api/v1/requests/:id hasta processed. Decisión: positive, negative o inconclusive.

curl -sS https://orbi.orbitrack.us/api/v1/verify \
  -H "Authorization: Bearer $ORBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_serial_id": "ERP-10042",
    "image_object_key": "'"$OBJECT_KEY"'",
    "idempotency_key": "verify-erp-001"
  }'

curl -sS https://orbi.orbitrack.us/api/v1/requests/$REQUEST_ID \
  -H "Authorization: Bearer $ORBI_KEY"

9. Identify 1:N

Solo busca dentro del tenant de la key. Misma cola asíncrona (202 + poll).

curl -sS https://orbi.orbitrack.us/api/v1/identify \
  -H "Authorization: Bearer $ORBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_object_key": "'"$OBJECT_KEY"'",
    "idempotency_key": "identify-001",
    "top_k": 5
  }'

10. Idempotencia, límites y suspensión

• Campo idempotency_key (mín. 8) en complete, verify e identify. La misma clave en el mismo tenant reutiliza el trabajo.
• Rate limits por minuto y tenant: lectura de activos 120, escritura 60, verify 30, identify 20. Exceso → 429.
• Tenant suspendido → 403 tenant_suspended.