cord-sdk 1.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cord_sdk-1.1.0/.gitignore +4 -0
- cord_sdk-1.1.0/CHANGELOG.md +48 -0
- cord_sdk-1.1.0/PKG-INFO +211 -0
- cord_sdk-1.1.0/README.md +182 -0
- cord_sdk-1.1.0/pyproject.toml +51 -0
- cord_sdk-1.1.0/src/cord/__init__.py +25 -0
- cord_sdk-1.1.0/src/cord/_http.py +489 -0
- cord_sdk-1.1.0/src/cord/_version.py +2 -0
- cord_sdk-1.1.0/src/cord/async_client.py +322 -0
- cord_sdk-1.1.0/src/cord/client.py +359 -0
- cord_sdk-1.1.0/src/cord/py.typed +0 -0
- cord_sdk-1.1.0/src/cord/types.py +1900 -0
- cord_sdk-1.1.0/src/cord/webhooks.py +195 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [1.1.0] — 2026-11-04
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- `AsyncCord`: el mismo cliente con `await` y `async for`, sobre httpx (`pip install 'cord-sdk[async]'`) o el `transport` que pases. Comparte con `Cord` la idempotencia, los reintentos y los errores.
|
|
8
|
+
- `cord.types`: un `TypedDict` por objeto de la API, generado de la spec OpenAPI (`npm run sdk:types`), con los mismos nombres que el SDK de Node. Los argumentos de `create`, `update`, `list` y `list_all` están tipados y el paquete pasa `mypy --strict`.
|
|
9
|
+
- Un `Decimal` se manda como número y un `date` o `datetime` como fecha ISO 8601, en el cuerpo y en los filtros (antes, un `TypeError`); un booleano en un filtro va como `true` o `false`.
|
|
10
|
+
- `cord.workflows.invoke(workflow_id, objeto, ids)`: corre un workflow "Lo corres tú" sobre cotizaciones o facturas (`POST /workflows/{id}/invoke`).
|
|
11
|
+
- `cord.setup.propose(sitio=, descripcion=, archivo=)` y `cord.setup.retrieve(plan_id)`: propone una configuración de la cuenta y consulta su estado (`/setup/plans`).
|
|
12
|
+
- `cord.elements.config()`. `cord.elements_config()` sigue funcionando.
|
|
13
|
+
- `invoices.finalize(invoice_id, sin_comercio_exterior=True)`: confirma que un CFDI a un cliente extranjero no lleva mercancías.
|
|
14
|
+
- `verify_signature(payload, headers, secret)`: comprueba la firma de cualquier envío de Cord sin leer el cuerpo.
|
|
15
|
+
- `construct_workflow_delivery(payload, headers, secret)`: verifica y decodifica el POST de la acción "Mandar los datos a una URL" de Cord Workflows.
|
|
16
|
+
- `construct_event`, `verify_signature` y `construct_workflow_delivery` aceptan también Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`); con las dos firmas basta con que cuadre una. Las tres cuelgan también de `cord.webhooks`.
|
|
17
|
+
- `create_task()` acepta `factura_id`.
|
|
18
|
+
- `quotes.update(quote_id, **params)`: edita un borrador; lo que pasas reemplaza a lo guardado y lo que no pasas se conserva.
|
|
19
|
+
- `products.retrieve`, `products.update` y `products.delete` (`/productos/{id}`).
|
|
20
|
+
- `webhook_endpoints.update(endpoint_id, url=, eventos=, activo=)` y `webhook_endpoints.rotate_secret(endpoint_id, ventana_horas=None)`: el secreto anterior sigue firmando 1, 24 o 72 horas junto al nuevo.
|
|
21
|
+
- `test_helpers.reset()`: vacía los datos del entorno de prueba y conserva las llaves y los endpoints de webhook.
|
|
22
|
+
- `cord.raw_request(method, path, query=, body=, idempotency_key=, headers=)` devuelve un `RawResponse` (`data`, `meta`, `request_id`, `last_response`): una ruta sin método propio con la llave, la idempotencia, los reintentos y los errores ya puestos. La ruta es relativa a `/api/v1`; una URL absoluta, `//host`, `.` o `..` son un `ValueError` antes de la red.
|
|
23
|
+
- `cord.last_response`: un `CordResponse` (`status`, `headers`, `request_id`, `idempotent_replayed`, `api_version`) de la última llamada exitosa, guardado en una variable de contexto: correcto por hilo y por tarea de asyncio.
|
|
24
|
+
- `cord.with_options(timeout=, max_retries=)`: un cliente con otras opciones que comparte transporte y `last_response` con el original.
|
|
25
|
+
- `app_info={"name": ..., "version": ...}` agrega tu app al `User-Agent` (`cord-python/1.1.0 mi-erp/4.2.0`).
|
|
26
|
+
- `CordError.headers` y `CordError.retry_after`.
|
|
27
|
+
- `API_VERSION` sale de `cord.types`, generado del contrato de la API, y la versión del paquete de `cord/_version.py`, que también lee `pyproject.toml`.
|
|
28
|
+
|
|
29
|
+
### Changed
|
|
30
|
+
|
|
31
|
+
- Requiere Python 3.10 o posterior: Python 3.9 dejó de tener soporte en octubre de 2025.
|
|
32
|
+
- `idempotency_key` se pasa siempre por nombre. Antes era el primer argumento posicional de `create` y `update`: `cord.quotes.create({...})` mandaba el cuerpo vacío y metía el diccionario en el header `Idempotency-Key`. Ahora es un `TypeError`.
|
|
33
|
+
- Solo se reintenta un fallo de red (`ConnectionError`, `TimeoutError`, `URLError`). Antes cualquier excepción del transporte, también un `TypeError` del propio código, se reintentaba y se reportaba como `network_error`.
|
|
34
|
+
- `list_all()` recorre por cursor también cotizaciones, clientes y productos (antes por `offset`, que salta o repite registros si alguien escribe mientras recorres). Acepta `limit=` como tamaño de página, que antes lanzaba `TypeError`, y `products.list_all()` acepta filtros. Pasarle `offset` o `cursor` es un `TypeError`.
|
|
35
|
+
- Las firmas de los webhooks se verifican sobre los bytes crudos: un cuerpo que no es UTF-8 da `signature_mismatch` en lugar de `UnicodeDecodeError`, igual que en los SDK de Node y PHP.
|
|
36
|
+
- El transporte respeta `Cord-Should-Retry`: `false` no reintenta esa respuesta aunque sea un 5xx, y `true` la reintenta aunque su status no esté en la lista.
|
|
37
|
+
- Sin secreto, `construct_event` lanza `missing_secret` (antes `missing_signature`).
|
|
38
|
+
- Reintentos: `Cord-Should-Retry` manda siempre. Sin él se reintenta la red caída, `408`, `425` y `5xx`; un `429` solo con `code` `rate_limited` o sin `code`. Una cuota agotada (`api_quota_exceeded`, `ai_quota_exceeded`) sale de inmediato. Las esperas suman como mucho 60 s por llamada; un `Retry-After` que no cabe ya no se recorta: sale el error. `409 idempotency_in_progress` no gasta reintentos y se vuelve a preguntar hasta la respuesta guardada. `Retry-After` se lee también como fecha HTTP.
|
|
39
|
+
- Nunca sigue una redirección: el transporte de urllib usa un opener sin redirecciones (antes un `302` de un `POST` llegaba como `GET`) y httpx va con `follow_redirects=False`. Un `3xx` es `CordError` con `code` `unexpected_redirect`, sin reintento.
|
|
40
|
+
- Las pruebas verifican los vectores de `test/fixtures/webhook-vectors.json`, firmados con el firmador del servidor, los mismos que verifican los SDK de Node y PHP, con los casos de un `t` con dígitos que no son ASCII y de un cuerpo que no es UTF-8.
|
|
41
|
+
|
|
42
|
+
## [1.0.0] — nunca publicada
|
|
43
|
+
|
|
44
|
+
Primera versión, en el repositorio; no se publicó en PyPI.
|
|
45
|
+
|
|
46
|
+
- API v1: cotizaciones, clientes, productos, facturas, cobranza, eventos, tareas, endpoints de webhook, configuración de Elements y `test_helpers`.
|
|
47
|
+
- `Idempotency-Key` automática en toda mutación, la misma en cada reintento; reintentos con `Retry-After`; errores `CordError` con `code`, `request_id` y `doc_url`.
|
|
48
|
+
- `construct_event` exige la firma V1 con timestamp; la legacy solo con `allow_legacy_signature=True`.
|
cord_sdk-1.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: cord-sdk
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: SDK de Python para la API de Cord: cotizaciones, facturas, webhooks verificados, tipos y cliente async. Sin dependencias.
|
|
5
|
+
Project-URL: Homepage, https://cordhq.app
|
|
6
|
+
Project-URL: Documentation, https://docs.cordhq.app/docs/desarrolladores/herramientas/sdks
|
|
7
|
+
Project-URL: API reference, https://docs.cordhq.app/docs/desarrolladores/referencia
|
|
8
|
+
Author: Flouvia
|
|
9
|
+
License: MIT
|
|
10
|
+
Keywords: api,async,cord,cotizaciones,facturas,webhooks
|
|
11
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
12
|
+
Classifier: Framework :: AsyncIO
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.10
|
|
26
|
+
Provides-Extra: async
|
|
27
|
+
Requires-Dist: httpx>=0.27; extra == 'async'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# cord-sdk (Python)
|
|
31
|
+
|
|
32
|
+
SDK de Python para la API de [Cord](https://cordhq.app). Sin dependencias, Python 3.10+, con tipos y cliente async.
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install cord-sdk
|
|
36
|
+
pip install 'cord-sdk[async]' # AsyncCord, con httpx
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
from cord import Cord
|
|
41
|
+
|
|
42
|
+
cord = Cord("sk_test_...")
|
|
43
|
+
quote = cord.quotes.create(
|
|
44
|
+
cliente={"empresa": "Acme"},
|
|
45
|
+
items=[{"descripcion": "Instalación", "cantidad": 1, "precio_unitario": 12500, "tax_rate": 0.16}],
|
|
46
|
+
base_currency="MXN",
|
|
47
|
+
)
|
|
48
|
+
print(quote["folio"], quote["link_publico"])
|
|
49
|
+
|
|
50
|
+
for invoice in cord.invoices.list_all(estado="open"):
|
|
51
|
+
print(invoice["numero"], invoice["saldo"], invoice["moneda"])
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
- Toda mutación lleva `Idempotency-Key`, la misma en cada reintento: un corte de red nunca duplica nada. Pasa `idempotency_key=` (siempre por nombre) para atarla a tu propio identificador.
|
|
55
|
+
- `list_all()` recorre por cursor: no salta ni repite registros aunque alguien escriba mientras recorres. Acepta los filtros de `list()` y `limit=` como tamaño de cada página.
|
|
56
|
+
- Los errores son `CordError` con `status`, `code`, `request_id`, `doc_url`, `headers` y `retry_after`. Un error de tu código, como un `TypeError`, sale tal cual y no se reintenta.
|
|
57
|
+
- Manda `Cord-Version: 2026-10-01`; cámbiala con `Cord(sk, api_version=...)`.
|
|
58
|
+
- Un `Decimal` se manda como número y un `date` o `datetime` como fecha ISO 8601, en el cuerpo y en los filtros. Los tipos siguen la spec (`float` y `str`), salvo `record_payment` y `credit_note`, que aceptan `Decimal`.
|
|
59
|
+
|
|
60
|
+
## Reintentos
|
|
61
|
+
|
|
62
|
+
- Si la respuesta trae `Cord-Should-Retry`, manda ese header: `false` no se reintenta (una cuota agotada, el tope de envíos de una factura, un rechazo del PAC al emitir) y `true` sí.
|
|
63
|
+
- Sin él se reintenta la red caída (`ConnectionError`, `TimeoutError` o `URLError`), 408, 425 y 5xx. Un 429 solo si es de ritmo (`code` `rate_limited`) o llega sin `code`, como el de un proxy; uno de cuota agotada (`api_quota_exceeded`, `ai_quota_exceeded`) sale de inmediato.
|
|
64
|
+
- Se espera lo que diga `Retry-After` (segundos o fecha HTTP) o un backoff exponencial, y todas las esperas de una llamada suman como mucho 60 s. Si la siguiente no cabe, sale el `CordError`, con `retry_after` para que decidas tú cuándo volver.
|
|
65
|
+
- `409 idempotency_in_progress` (la misma clave sigue en curso) no gasta reintentos: el SDK vuelve a preguntar hasta recibir la respuesta guardada, así un `finalize` lento termina con la factura. `max_retries=0` apaga todo reintento.
|
|
66
|
+
- Nunca sigue una redirección: un 3xx es `CordError` con `code` `unexpected_redirect` y la dirección a la que apunta. Revisa `base_url` (la de producción es `https://cordhq.app`).
|
|
67
|
+
|
|
68
|
+
## Opciones por llamada, respuesta y rutas sin método
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
cord = Cord("sk_test_...", app_info={"name": "mi-erp", "version": "4.2.0"}) # User-Agent: cord-python/1.1.0 mi-erp/4.2.0
|
|
72
|
+
|
|
73
|
+
rapido = cord.with_options(timeout=5.0, max_retries=0)
|
|
74
|
+
rapido.invoices.finalize(factura_id)
|
|
75
|
+
print(cord.last_response.request_id) # búscalo en Desarrolladores › Registros
|
|
76
|
+
|
|
77
|
+
r = cord.raw_request("GET", "/cotizaciones", query={"status": "sent", "limit": 5})
|
|
78
|
+
print(r.data, r.meta, r.request_id)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
- `with_options(timeout=, max_retries=)` devuelve un cliente con esas opciones que comparte transporte y `last_response` con el original.
|
|
82
|
+
- `last_response` es un `CordResponse` (`status`, `headers`, `request_id`, `idempotent_replayed`, `api_version`) de la última llamada exitosa de ese hilo o esa tarea de asyncio.
|
|
83
|
+
- `raw_request(method, path, query=, body=, idempotency_key=, headers=)` llama una ruta que el SDK aún no tiene como método, con la llave, `Cord-Version`, la idempotencia, los reintentos y los errores ya puestos, y devuelve un `RawResponse`. La ruta es relativa a `/api/v1` (`/api/v1/…` también vale); una URL absoluta, `//host`, `.` o `..` son un `ValueError`: la llave nunca sale a otro host.
|
|
84
|
+
|
|
85
|
+
## Tipos
|
|
86
|
+
|
|
87
|
+
Cada respuesta es un `TypedDict` de `cord.types`, generado de la spec OpenAPI con los mismos nombres que el SDK de Node (`Quote`, `QuoteDetail`, `Invoice`, `InvoiceDetail`, `Client`, `Product`…). Los argumentos de `create`, `update`, `list` y `list_all` también están tipados: mypy o Pyright marcan un campo mal escrito antes de llamar a Cord.
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from cord.types import InvoiceDetail
|
|
91
|
+
|
|
92
|
+
factura: InvoiceDetail = cord.invoices.retrieve(factura_id)
|
|
93
|
+
print(factura["saldo"], factura["moneda"])
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Async
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
from cord import AsyncCord
|
|
100
|
+
|
|
101
|
+
async with AsyncCord("sk_test_...") as cord:
|
|
102
|
+
quote = await cord.quotes.create(items=[{"descripcion": "Instalación", "cantidad": 1, "precio_unitario": 12500}])
|
|
103
|
+
async for invoice in cord.invoices.list_all(estado="open"):
|
|
104
|
+
print(invoice["numero"])
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`AsyncCord` tiene los mismos métodos que `Cord`, con la misma idempotencia y los mismos reintentos. Usa httpx; con `transport=` puedes pasar el tuyo (una función async que recibe `method, url, headers, body, timeout` y devuelve `status, headers, body`).
|
|
108
|
+
|
|
109
|
+
## Recursos
|
|
110
|
+
|
|
111
|
+
| Atributo | Métodos |
|
|
112
|
+
|---|---|
|
|
113
|
+
| `cord.me()`, `cord.collections()`, `cord.create_task(...)` | `GET /me`, `GET /cobranza`, `POST /tareas` |
|
|
114
|
+
| `cord.quotes` | `list`, `list_all`, `retrieve`, `create`, `update`, `send`, `resend`, `approve`, `reject`, `mark_paid`, `delete`, `draft_from_text` |
|
|
115
|
+
| `cord.clients` | `list`, `list_all`, `retrieve`, `create`, `update` |
|
|
116
|
+
| `cord.products` | `list`, `list_all`, `retrieve`, `create`, `update`, `delete` |
|
|
117
|
+
| `cord.invoices` | `list`, `list_all`, `retrieve`, `create`, `finalize`, `send`, `void`, `record_payment`, `credit_note` |
|
|
118
|
+
| `cord.events` | `list`, `list_all` |
|
|
119
|
+
| `cord.workflows` | `invoke` |
|
|
120
|
+
| `cord.setup` | `propose`, `retrieve` |
|
|
121
|
+
| `cord.elements` | `config` |
|
|
122
|
+
| `cord.webhook_endpoints` | `list`, `create`, `update`, `rotate_secret`, `delete` |
|
|
123
|
+
| `cord.test_helpers` | `reset`, `set_next_fiscal_outcome`, `view_quote`, `expire_quote`, `trigger_webhook` (solo `sk_test_`) |
|
|
124
|
+
| `cord.webhooks` | `construct_event`, `construct_workflow_delivery`, `verify_signature`, `sign_payload` |
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
factura = cord.invoices.create(cliente_id=cliente_id, items=[...], currency="MXN")
|
|
128
|
+
# Un CFDI a un cliente extranjero sin mercancías: confírmalo al emitir.
|
|
129
|
+
cord.invoices.finalize(factura["id"], sin_comercio_exterior=True)
|
|
130
|
+
|
|
131
|
+
cord.workflows.invoke("wf_…", "invoice", [factura["id"]])
|
|
132
|
+
|
|
133
|
+
plan = cord.setup.propose(sitio="tunegocio.com", descripcion="Instalaciones eléctricas, cobro a 30 días")
|
|
134
|
+
print(plan["review_url"]) # una persona la aprueba ahí
|
|
135
|
+
|
|
136
|
+
cord.webhook_endpoints.update(endpoint_id, activo=False) # lo pausa
|
|
137
|
+
nuevo = cord.webhook_endpoints.rotate_secret(endpoint_id, 72)
|
|
138
|
+
print(nuevo["secret"], nuevo["secreto_anterior_expira"]) # el anterior sigue firmando 72 horas
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Webhooks
|
|
142
|
+
|
|
143
|
+
Verifica siempre sobre el cuerpo **crudo**, tal como llegó.
|
|
144
|
+
|
|
145
|
+
Flask:
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
import os
|
|
149
|
+
from flask import Flask, request
|
|
150
|
+
from cord import construct_event, WebhookSignatureError
|
|
151
|
+
|
|
152
|
+
app = Flask(__name__)
|
|
153
|
+
|
|
154
|
+
@app.post("/webhooks/cord")
|
|
155
|
+
def cord_webhook():
|
|
156
|
+
try:
|
|
157
|
+
event = construct_event(request.get_data(), request.headers, os.environ["CORD_WEBHOOK_SECRET"])
|
|
158
|
+
except WebhookSignatureError:
|
|
159
|
+
return "", 400
|
|
160
|
+
if event["event"] == "invoice.paid":
|
|
161
|
+
...
|
|
162
|
+
return "ok"
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
FastAPI:
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
import os
|
|
169
|
+
from fastapi import FastAPI, Request, Response
|
|
170
|
+
from cord import construct_event, WebhookSignatureError
|
|
171
|
+
|
|
172
|
+
app = FastAPI()
|
|
173
|
+
|
|
174
|
+
@app.post("/webhooks/cord")
|
|
175
|
+
async def cord_webhook(request: Request) -> Response:
|
|
176
|
+
try:
|
|
177
|
+
event = construct_event(await request.body(), request.headers, os.environ["CORD_WEBHOOK_SECRET"])
|
|
178
|
+
except WebhookSignatureError:
|
|
179
|
+
return Response(status_code=400)
|
|
180
|
+
if event["event"] == "invoice.paid":
|
|
181
|
+
...
|
|
182
|
+
return Response("ok")
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
En Django, el cuerpo crudo es `request.body` y la vista va con `@csrf_exempt`.
|
|
186
|
+
|
|
187
|
+
Usa el cuerpo crudo. Acepta `X-Cord-Signature-V1` o Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), ambas con timestamp (5 minutos de tolerancia, `tolerance=`); con las dos basta con que cuadre una. La firma legacy solo con `allow_legacy_signature=True`. Deduplica por `event["id"]`.
|
|
188
|
+
|
|
189
|
+
`WebhookSignatureError.code`: `missing_secret`, `missing_signature`, `invalid_signature_header`, `timestamp_out_of_tolerance`, `signature_mismatch`, `legacy_signature_rejected` o `invalid_payload`.
|
|
190
|
+
|
|
191
|
+
### El POST de un workflow
|
|
192
|
+
|
|
193
|
+
La acción "Mandar los datos a una URL" de Cord Workflows firma su POST igual, pero su cuerpo es `{ workflow, workflow_id, evento, objeto, objeto_id, enviado_en, mensaje?, datos }`:
|
|
194
|
+
|
|
195
|
+
```python
|
|
196
|
+
from cord import construct_workflow_delivery
|
|
197
|
+
|
|
198
|
+
envio = construct_workflow_delivery(request.get_data(), request.headers, os.environ["CORD_WORKFLOW_SECRET"])
|
|
199
|
+
print(envio["evento"], envio["datos"])
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`verify_signature(payload, headers, secret)` solo comprueba la firma, sin leer el cuerpo.
|
|
203
|
+
|
|
204
|
+
## Modo prueba
|
|
205
|
+
|
|
206
|
+
```python
|
|
207
|
+
cord = Cord("sk_test_...")
|
|
208
|
+
cord.test_helpers.set_next_fiscal_outcome("pac_caido")
|
|
209
|
+
cord.test_helpers.trigger_webhook("invoice.paid")
|
|
210
|
+
cord.test_helpers.reset() # vacía el entorno de prueba; conserva llaves y endpoints
|
|
211
|
+
```
|
cord_sdk-1.1.0/README.md
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# cord-sdk (Python)
|
|
2
|
+
|
|
3
|
+
SDK de Python para la API de [Cord](https://cordhq.app). Sin dependencias, Python 3.10+, con tipos y cliente async.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pip install cord-sdk
|
|
7
|
+
pip install 'cord-sdk[async]' # AsyncCord, con httpx
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
```python
|
|
11
|
+
from cord import Cord
|
|
12
|
+
|
|
13
|
+
cord = Cord("sk_test_...")
|
|
14
|
+
quote = cord.quotes.create(
|
|
15
|
+
cliente={"empresa": "Acme"},
|
|
16
|
+
items=[{"descripcion": "Instalación", "cantidad": 1, "precio_unitario": 12500, "tax_rate": 0.16}],
|
|
17
|
+
base_currency="MXN",
|
|
18
|
+
)
|
|
19
|
+
print(quote["folio"], quote["link_publico"])
|
|
20
|
+
|
|
21
|
+
for invoice in cord.invoices.list_all(estado="open"):
|
|
22
|
+
print(invoice["numero"], invoice["saldo"], invoice["moneda"])
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- Toda mutación lleva `Idempotency-Key`, la misma en cada reintento: un corte de red nunca duplica nada. Pasa `idempotency_key=` (siempre por nombre) para atarla a tu propio identificador.
|
|
26
|
+
- `list_all()` recorre por cursor: no salta ni repite registros aunque alguien escriba mientras recorres. Acepta los filtros de `list()` y `limit=` como tamaño de cada página.
|
|
27
|
+
- Los errores son `CordError` con `status`, `code`, `request_id`, `doc_url`, `headers` y `retry_after`. Un error de tu código, como un `TypeError`, sale tal cual y no se reintenta.
|
|
28
|
+
- Manda `Cord-Version: 2026-10-01`; cámbiala con `Cord(sk, api_version=...)`.
|
|
29
|
+
- Un `Decimal` se manda como número y un `date` o `datetime` como fecha ISO 8601, en el cuerpo y en los filtros. Los tipos siguen la spec (`float` y `str`), salvo `record_payment` y `credit_note`, que aceptan `Decimal`.
|
|
30
|
+
|
|
31
|
+
## Reintentos
|
|
32
|
+
|
|
33
|
+
- Si la respuesta trae `Cord-Should-Retry`, manda ese header: `false` no se reintenta (una cuota agotada, el tope de envíos de una factura, un rechazo del PAC al emitir) y `true` sí.
|
|
34
|
+
- Sin él se reintenta la red caída (`ConnectionError`, `TimeoutError` o `URLError`), 408, 425 y 5xx. Un 429 solo si es de ritmo (`code` `rate_limited`) o llega sin `code`, como el de un proxy; uno de cuota agotada (`api_quota_exceeded`, `ai_quota_exceeded`) sale de inmediato.
|
|
35
|
+
- Se espera lo que diga `Retry-After` (segundos o fecha HTTP) o un backoff exponencial, y todas las esperas de una llamada suman como mucho 60 s. Si la siguiente no cabe, sale el `CordError`, con `retry_after` para que decidas tú cuándo volver.
|
|
36
|
+
- `409 idempotency_in_progress` (la misma clave sigue en curso) no gasta reintentos: el SDK vuelve a preguntar hasta recibir la respuesta guardada, así un `finalize` lento termina con la factura. `max_retries=0` apaga todo reintento.
|
|
37
|
+
- Nunca sigue una redirección: un 3xx es `CordError` con `code` `unexpected_redirect` y la dirección a la que apunta. Revisa `base_url` (la de producción es `https://cordhq.app`).
|
|
38
|
+
|
|
39
|
+
## Opciones por llamada, respuesta y rutas sin método
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
cord = Cord("sk_test_...", app_info={"name": "mi-erp", "version": "4.2.0"}) # User-Agent: cord-python/1.1.0 mi-erp/4.2.0
|
|
43
|
+
|
|
44
|
+
rapido = cord.with_options(timeout=5.0, max_retries=0)
|
|
45
|
+
rapido.invoices.finalize(factura_id)
|
|
46
|
+
print(cord.last_response.request_id) # búscalo en Desarrolladores › Registros
|
|
47
|
+
|
|
48
|
+
r = cord.raw_request("GET", "/cotizaciones", query={"status": "sent", "limit": 5})
|
|
49
|
+
print(r.data, r.meta, r.request_id)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
- `with_options(timeout=, max_retries=)` devuelve un cliente con esas opciones que comparte transporte y `last_response` con el original.
|
|
53
|
+
- `last_response` es un `CordResponse` (`status`, `headers`, `request_id`, `idempotent_replayed`, `api_version`) de la última llamada exitosa de ese hilo o esa tarea de asyncio.
|
|
54
|
+
- `raw_request(method, path, query=, body=, idempotency_key=, headers=)` llama una ruta que el SDK aún no tiene como método, con la llave, `Cord-Version`, la idempotencia, los reintentos y los errores ya puestos, y devuelve un `RawResponse`. La ruta es relativa a `/api/v1` (`/api/v1/…` también vale); una URL absoluta, `//host`, `.` o `..` son un `ValueError`: la llave nunca sale a otro host.
|
|
55
|
+
|
|
56
|
+
## Tipos
|
|
57
|
+
|
|
58
|
+
Cada respuesta es un `TypedDict` de `cord.types`, generado de la spec OpenAPI con los mismos nombres que el SDK de Node (`Quote`, `QuoteDetail`, `Invoice`, `InvoiceDetail`, `Client`, `Product`…). Los argumentos de `create`, `update`, `list` y `list_all` también están tipados: mypy o Pyright marcan un campo mal escrito antes de llamar a Cord.
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
from cord.types import InvoiceDetail
|
|
62
|
+
|
|
63
|
+
factura: InvoiceDetail = cord.invoices.retrieve(factura_id)
|
|
64
|
+
print(factura["saldo"], factura["moneda"])
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Async
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
from cord import AsyncCord
|
|
71
|
+
|
|
72
|
+
async with AsyncCord("sk_test_...") as cord:
|
|
73
|
+
quote = await cord.quotes.create(items=[{"descripcion": "Instalación", "cantidad": 1, "precio_unitario": 12500}])
|
|
74
|
+
async for invoice in cord.invoices.list_all(estado="open"):
|
|
75
|
+
print(invoice["numero"])
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`AsyncCord` tiene los mismos métodos que `Cord`, con la misma idempotencia y los mismos reintentos. Usa httpx; con `transport=` puedes pasar el tuyo (una función async que recibe `method, url, headers, body, timeout` y devuelve `status, headers, body`).
|
|
79
|
+
|
|
80
|
+
## Recursos
|
|
81
|
+
|
|
82
|
+
| Atributo | Métodos |
|
|
83
|
+
|---|---|
|
|
84
|
+
| `cord.me()`, `cord.collections()`, `cord.create_task(...)` | `GET /me`, `GET /cobranza`, `POST /tareas` |
|
|
85
|
+
| `cord.quotes` | `list`, `list_all`, `retrieve`, `create`, `update`, `send`, `resend`, `approve`, `reject`, `mark_paid`, `delete`, `draft_from_text` |
|
|
86
|
+
| `cord.clients` | `list`, `list_all`, `retrieve`, `create`, `update` |
|
|
87
|
+
| `cord.products` | `list`, `list_all`, `retrieve`, `create`, `update`, `delete` |
|
|
88
|
+
| `cord.invoices` | `list`, `list_all`, `retrieve`, `create`, `finalize`, `send`, `void`, `record_payment`, `credit_note` |
|
|
89
|
+
| `cord.events` | `list`, `list_all` |
|
|
90
|
+
| `cord.workflows` | `invoke` |
|
|
91
|
+
| `cord.setup` | `propose`, `retrieve` |
|
|
92
|
+
| `cord.elements` | `config` |
|
|
93
|
+
| `cord.webhook_endpoints` | `list`, `create`, `update`, `rotate_secret`, `delete` |
|
|
94
|
+
| `cord.test_helpers` | `reset`, `set_next_fiscal_outcome`, `view_quote`, `expire_quote`, `trigger_webhook` (solo `sk_test_`) |
|
|
95
|
+
| `cord.webhooks` | `construct_event`, `construct_workflow_delivery`, `verify_signature`, `sign_payload` |
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
factura = cord.invoices.create(cliente_id=cliente_id, items=[...], currency="MXN")
|
|
99
|
+
# Un CFDI a un cliente extranjero sin mercancías: confírmalo al emitir.
|
|
100
|
+
cord.invoices.finalize(factura["id"], sin_comercio_exterior=True)
|
|
101
|
+
|
|
102
|
+
cord.workflows.invoke("wf_…", "invoice", [factura["id"]])
|
|
103
|
+
|
|
104
|
+
plan = cord.setup.propose(sitio="tunegocio.com", descripcion="Instalaciones eléctricas, cobro a 30 días")
|
|
105
|
+
print(plan["review_url"]) # una persona la aprueba ahí
|
|
106
|
+
|
|
107
|
+
cord.webhook_endpoints.update(endpoint_id, activo=False) # lo pausa
|
|
108
|
+
nuevo = cord.webhook_endpoints.rotate_secret(endpoint_id, 72)
|
|
109
|
+
print(nuevo["secret"], nuevo["secreto_anterior_expira"]) # el anterior sigue firmando 72 horas
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Webhooks
|
|
113
|
+
|
|
114
|
+
Verifica siempre sobre el cuerpo **crudo**, tal como llegó.
|
|
115
|
+
|
|
116
|
+
Flask:
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
import os
|
|
120
|
+
from flask import Flask, request
|
|
121
|
+
from cord import construct_event, WebhookSignatureError
|
|
122
|
+
|
|
123
|
+
app = Flask(__name__)
|
|
124
|
+
|
|
125
|
+
@app.post("/webhooks/cord")
|
|
126
|
+
def cord_webhook():
|
|
127
|
+
try:
|
|
128
|
+
event = construct_event(request.get_data(), request.headers, os.environ["CORD_WEBHOOK_SECRET"])
|
|
129
|
+
except WebhookSignatureError:
|
|
130
|
+
return "", 400
|
|
131
|
+
if event["event"] == "invoice.paid":
|
|
132
|
+
...
|
|
133
|
+
return "ok"
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
FastAPI:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
import os
|
|
140
|
+
from fastapi import FastAPI, Request, Response
|
|
141
|
+
from cord import construct_event, WebhookSignatureError
|
|
142
|
+
|
|
143
|
+
app = FastAPI()
|
|
144
|
+
|
|
145
|
+
@app.post("/webhooks/cord")
|
|
146
|
+
async def cord_webhook(request: Request) -> Response:
|
|
147
|
+
try:
|
|
148
|
+
event = construct_event(await request.body(), request.headers, os.environ["CORD_WEBHOOK_SECRET"])
|
|
149
|
+
except WebhookSignatureError:
|
|
150
|
+
return Response(status_code=400)
|
|
151
|
+
if event["event"] == "invoice.paid":
|
|
152
|
+
...
|
|
153
|
+
return Response("ok")
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
En Django, el cuerpo crudo es `request.body` y la vista va con `@csrf_exempt`.
|
|
157
|
+
|
|
158
|
+
Usa el cuerpo crudo. Acepta `X-Cord-Signature-V1` o Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), ambas con timestamp (5 minutos de tolerancia, `tolerance=`); con las dos basta con que cuadre una. La firma legacy solo con `allow_legacy_signature=True`. Deduplica por `event["id"]`.
|
|
159
|
+
|
|
160
|
+
`WebhookSignatureError.code`: `missing_secret`, `missing_signature`, `invalid_signature_header`, `timestamp_out_of_tolerance`, `signature_mismatch`, `legacy_signature_rejected` o `invalid_payload`.
|
|
161
|
+
|
|
162
|
+
### El POST de un workflow
|
|
163
|
+
|
|
164
|
+
La acción "Mandar los datos a una URL" de Cord Workflows firma su POST igual, pero su cuerpo es `{ workflow, workflow_id, evento, objeto, objeto_id, enviado_en, mensaje?, datos }`:
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
from cord import construct_workflow_delivery
|
|
168
|
+
|
|
169
|
+
envio = construct_workflow_delivery(request.get_data(), request.headers, os.environ["CORD_WORKFLOW_SECRET"])
|
|
170
|
+
print(envio["evento"], envio["datos"])
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`verify_signature(payload, headers, secret)` solo comprueba la firma, sin leer el cuerpo.
|
|
174
|
+
|
|
175
|
+
## Modo prueba
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
cord = Cord("sk_test_...")
|
|
179
|
+
cord.test_helpers.set_next_fiscal_outcome("pac_caido")
|
|
180
|
+
cord.test_helpers.trigger_webhook("invoice.paid")
|
|
181
|
+
cord.test_helpers.reset() # vacía el entorno de prueba; conserva llaves y endpoints
|
|
182
|
+
```
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling==1.32.4"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "cord-sdk"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "SDK de Python para la API de Cord: cotizaciones, facturas, webhooks verificados, tipos y cliente async. Sin dependencias."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [{ name = "Flouvia" }]
|
|
13
|
+
keywords = ["cord", "cotizaciones", "facturas", "webhooks", "api", "async"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 5 - Production/Stable",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Programming Language :: Python :: 3.14",
|
|
26
|
+
"Framework :: AsyncIO",
|
|
27
|
+
"Topic :: Office/Business :: Financial",
|
|
28
|
+
"Typing :: Typed",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
async = ["httpx>=0.27"]
|
|
33
|
+
|
|
34
|
+
[project.urls]
|
|
35
|
+
Homepage = "https://cordhq.app"
|
|
36
|
+
Documentation = "https://docs.cordhq.app/docs/desarrolladores/herramientas/sdks"
|
|
37
|
+
"API reference" = "https://docs.cordhq.app/docs/desarrolladores/referencia"
|
|
38
|
+
|
|
39
|
+
[tool.hatch.version]
|
|
40
|
+
path = "src/cord/_version.py"
|
|
41
|
+
|
|
42
|
+
[tool.hatch.build.targets.wheel]
|
|
43
|
+
packages = ["src/cord"]
|
|
44
|
+
|
|
45
|
+
[tool.hatch.build.targets.sdist]
|
|
46
|
+
include = ["src/cord", "README.md", "CHANGELOG.md"]
|
|
47
|
+
|
|
48
|
+
[tool.mypy]
|
|
49
|
+
strict = true
|
|
50
|
+
python_version = "3.10"
|
|
51
|
+
files = ["src"]
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""SDK de Python para la API de Cord."""
|
|
2
|
+
from . import types
|
|
3
|
+
from ._http import API_VERSION, SDK_VERSION, AppInfo, CordError, CordResponse, RawResponse
|
|
4
|
+
from ._version import __version__
|
|
5
|
+
from .async_client import AsyncCord
|
|
6
|
+
from .client import Cord
|
|
7
|
+
from .webhooks import WebhookSignatureError, construct_event, construct_workflow_delivery, sign_payload, verify_signature
|
|
8
|
+
|
|
9
|
+
__all__ = [
|
|
10
|
+
"Cord",
|
|
11
|
+
"AsyncCord",
|
|
12
|
+
"AppInfo",
|
|
13
|
+
"CordError",
|
|
14
|
+
"CordResponse",
|
|
15
|
+
"RawResponse",
|
|
16
|
+
"WebhookSignatureError",
|
|
17
|
+
"construct_event",
|
|
18
|
+
"construct_workflow_delivery",
|
|
19
|
+
"verify_signature",
|
|
20
|
+
"sign_payload",
|
|
21
|
+
"types",
|
|
22
|
+
"API_VERSION",
|
|
23
|
+
"SDK_VERSION",
|
|
24
|
+
"__version__",
|
|
25
|
+
]
|